This section is a worked example of how to make a call to the API.

The steps described are:

1. Viewing the reference documentation for the endpoint you want to call
2. How to add parameters to the call
3. How to add a request body to the call
4. How to add an access token to the call
5. How to handle errors
6. Interpreting the response
   
   

Scenario

This scenario shows you how to change a subscriber group's name using the API. To do this, you make a PATCH request to the /subscriber-groups/{subscriberGroupId} endpoint.

When you make an API call you can choose to make the request using your browser's search bar or you can use a utility such as Postman or cURL. This example shows you how to make a call using cURL.

Viewing the reference documentation

To find out what endpoints are available and what they can be used for, you can refer to the API reference documentation.

The information in the reference documentation provides you with an overview of the endpoints that are available in the API, what they are used for and the mandatory information you must include in your calls to each endpoint.

The information in the reference documentation includes:

• A list of all of the API's endpoints and descriptions of what each endpoint is used for
• The methods each endpoint accepts
• The parameters you can pass in to your calls
• The response and error codes the endpoint returns
• If the endpoint accepts a request body, an example request body is documented
• The content included in responses from the API

In this case you should refer to the documentation for the Subscriber Group endpoints.

Adding parameters

From the reference documentation for the PATCH/subscriber-groups/{subscriberGroupId} endpoint, you can see that the subscriberGroupId parameter is mandatory. If you don't include this parameter, the call will fail because you have not told the endpoint which group you want to modify.

In endpoint URLs, parameters are denoted in curly brackets {}. In this example you are using the /subscriber-groups/{subscriberGroupId} endpoint, so the parameter is {subscriberGroupId}.

For example, if the unique identifier of the group you want to edit is 20, your cURL request would read:

curl -X PATCH "https://api.iot-x.com/subscriber-groups/20"

Adding a request body

The reference documentation for this endpoint tells you that you need to include a request body in your call. For this endpoint, you use the request body to tell the endpoint what you want to change the group's name to.

Where a request body is required, the reference documentation details the format in which the body can be supplied, the fields you need to include in the request and the request body's structure. In this case you need to provide a JSON object which includes the name you want to apply to the group.

For example, if you want to change the group's name to "Charlie's Group", the request body would look like this:

{
  "name": "Charlie's Group"
}

Now that you have added parameters and a request body to the call, your cURL request looks like this:

curl -X PATCH "https://api.iot-x.com/subscriber-groups/20" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\":\"Charlie's Group\"}"

Adding your access token

You must provide your access token with every API call you make. You include your access token in the request's HTTP authorization header as a bearer credential.

For example, if your access token is: d567fde24865df35defff57862dw2r42, your cURL request would look like this:

curl -X PATCH "https://api.iot-x.com/subscriber-groups/20" -H "Authorization: Bearer d567fde24865df35defff57862dw2r42" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"name\":\"Charlie's Group\"}"

Handling errors

The API returns an error if your request could not be completed. For example, you might receive an error because:

• You did not provide a required parameter in the call
• You did not provide a valid request body in the call
• There was an error on our end

To help you interpret the cause of an error, the API returns a human-readable error message in the call's response body. The message explains what caused the error and helps you to troubleshoot it.

For example, in this scenario if you make a call to the PATCH/subscriber-groups/{subscriberGroupId} endpoint and you provide a subscriberGroupId that does not exist on your account, you will receive a 404 error.

This is an example of how the error appears in the response body:

{
 error: {
   code: 'INVALID_PROPERTY',
   message: 'Error caused because the subscriberGroupId does not match any of the account's subscriber groups.',
 }
}

Your response to the error will differ depending on the type of error that has been thrown.

Interpreting the response

If your request is successful, the endpoint returns a 200 response code and a response body. Every endpoint's Reference documentation includes a response example and a response schema. This provides you with an overview of the information that is returned by each endpoint. 

In this scenario, a 200 response means that the group's name has been successfully updated. The response body for a successful request to this endpoint returns an array of information relating to the group you updated.

An example response body for this endpoint looks like this:

{
  "content": {
    "id": 20,
    "name": "Charlie's Group",
    "hideTariffDetails": true,
    "numberOfUsersAttached": 5,
    "numberOfSubscribersAttached": 20
  }
}

In this example, you can see from the response body that:

• The group's unique identifier is 20 - this is represented in the id field.
• The group's name is Charlie's Group - this is represented in the name field.
• The users in the group cannot see billing information about the subscribers in the group - this is represented in the hideTariffDetails field.
• There are 5 users in the group - this is represented in the numberOfUsersAttached field.
• There are 20 subscribers in the group - this is represented in the numberOfSubscribersAttached field.