See a step-by-step example

This topic is a step-by-step example of how to make a call to the Connectivity Management API.

Note: You can make an API call using your browser's address bar, or you can use a utility such as Postman or cURL. This example shows you how to make a call using cURL.

Scenario

The example shows you how to edit a monitoring alert using the API. In this scenario, the API call updates the monitoring alert's upper and lower usage thresholds. To do this, you send a PATCH request to the /alerts/{id} endpoint.

View the reference documentation

The API Reference documentation describes the endpoints in the API, what they are used for, and the mandatory and optional information to include in your calls.

Request an access token

The Connectivity Management API uses access keys to validate that calls originate from permitted sources. To validate that you have permission to access the Connectivity Management API, you must create an access key and include it in your calls.

Info: For more information about access tokens, see the topic API authentication.

Add parameters

In this example, for the /alerts/{id} endpoint, the parameter is {id}.

From the reference documentation for this endpoint, you can see that you must include the "id" parameter for the alert that you want to edit. If you do not include this mandatory parameter in your request, the call results in an error.

To include a parameter in your request, replace the braces and the placeholder inside the braces with an actual value. For example, if the unique identifier of the monitoring alert you want to edit is 24, make the following cURL request.

curl -X PATCH "https://api.connectivity-us.pelion.com/alerts/24"

Tip: If you do not know the monitoring alert's unique identifier, you can retrieve it by making a GET request to the /alerts endpoint.

Info: For more information about parameters, see the topic Add path parameters.

Add a request body

From the reference documentation for this endpoint, you can see that you must provide a request body in your call. The reference documentation details the format, the fields to include in the request, and the request body's structure. For this call, the request body is used to update the monitoring alert's upper and lower usage thresholds.

The following example shows how to format the request body to update the lower threshold to 500KB and the upper threshold to 1MB.

 {
  "lowerThreshold": "512000"
  "upperThreshold": "1048576"
 }

The following example shows the request once you add the "id" parameter and request body

curl -X PATCH "https://api.connectivity-us.pelion.com/alerts/24" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"lowerThreshold\":\"1048576\",\"upperThreshold\":\"2097152\"}"

Info: For more information about request bodies, see the topic Add a request body.

Add your access token

To validate that you have permission to access the Connectivity Management API, you must include your access token as a bearer credential in your call's HTTP authorization header.

The following example is an illustration of how your call might look once you have added a parameter, request body, and access token.

curl -X PATCH "https://api.connectivity-us.pelion.com/alerts/24" -H "Authorization: Bearer d567fde24865df35defff57862dw2r42" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"lowerThreshold\":\"1048576\",\"upperThreshold\":\"2097152\"}"

Info: For more information about access tokens, see the topic API authentication.

Interpret the response

The endpoint returns a response code in the 200 range to indicate success, and a response body that contains the data you specified in your call. In this example, the /alerts endpoint returns an array of information about the monitoring alert you updated.

The following example shows how a response body from this endpoint might look

{
 "contents": [
  {
   "id": "24",
   "ruleType": "sim",
   "target": "447000000001",
   "lowerThreshold": "1048576",
   "upperThreshold": "2097152",
   "dateCreated": "2018-02-11T10:33:30.000Z"
  }
 ]
}

The response body is composed of the following parts:

  • The id field contains the monitoring alert's unique identifier.
  • The ruleType field contains the type of alert.
  • The target field contains the MSISDN of the subscriber to which the monitoring alert applies.
  • The lowerThreshold field contains the number of bytes for the lower usage threshold at which the alert is triggered .
  • The upperThreshold field contains the number of bytes for the upper usage threshold at which the alert is triggered.
  • The dateCreated field contains the date and time at which the alert was created.

Info: For more information about handling API responses, see the section Handle responses.