API resources and HTTP methods

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.



API resources

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:

  • API_BASE_URL/resource/{id}

For example:

  • 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. 

Info

The API's endpoints and their URLs are documented in the Reference section of this guide.



HTTP methods

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:

MethodDescription
GET

The GET method is used to retrieve data.

GET never causes data to be updated or changed.

POST

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.

PUT

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.

PATCH

The PATCH method is used to update a resource.

DELETEThe DELETE method is used to remove resources.

Info

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
GET "https://api.iot-x.com/subscriber-groups"