Resources and HTTP methods are used together to perform actions using the API.
This section outlines:
- What API resources are and how to interact with them.
- What HTTP methods are.
- An example of how to use resources and methods in an API call.
Resources are items you can perform actions on and retrieve information about using the API. The API includes resources such as "subscribers", "users" and "metadata". Every resource is identified by its own URL - this is usually referred to as an "endpoint". When you make an API call, the endpoint you make the call to identifies which resource (or collection of resources) you want to interact with.
The structure of the API follows a predictable, hierarchical structure. URLs are typically separated into the format:
- The API's base URL is: https://api.iot-x.com.
- To refer to a collection of resources, you add the collection's endpoint to the base URL. For example, to refer to all the subscriber groups on your account you add /subscriber-groups to the end of the base URL, like this: https://api.iot-x.com/subscriber-groups.
- To refer to a specific resource, you add the resource's unique identifier to the URL - this could be a value such as a user's unique ID. For example, to refer to a specific subscriber group, you can add the group's unique identifier to the end of the URL, like this: https://api.iot-x.com/subscriber-groups/20.
The API's endpoints and their URLs are documented in the Reference section of this guide.
HTTP methods, also known as HTTP verbs, define the type of action you want to perform on a resource. The most common methods are POST, GET, PUT, PATCH and DELETE. For example, when you want to retrieve data about a resource you use the GET method.
The API supports the following HTTP methods:
The GET method is used to retrieve data.
GET never causes data to be updated or changed.
The POST method is used to create new resources.
For example, making a POST request to the /users endpoint allows you to create a new user.
The PUT method is used to create or update a resource.
The difference between PUT and POST is that PUT is idempotent. This means you can call the same PUT request repeatedly and it always produces the same result. Calling a POST request repeatedly can cause the same resource to be created multiple times.
The PATCH method is used to update a resource.
|DELETE||The DELETE method is used to remove resources.|
The API only allows you to make requests using HTTPS.
Example API request
In an API call, you include the method you want to use before the resource endpoint. For example, if you want to retrieve information about the subscriber groups on your account, you make a GET request to: https://api.iot-x.com/subscriber-groups.
For this type of call, the request URL looks like this:
|Example GET Request|