Docs › Service API references › Using the APIs

Using the APIs

This section explains how the Device Management REST APIs work in general terms. If you've never worked with a REST API before, look at this tutorial.

This overview applies to using the APIs directly. The other methods are:

A software development kit (SDK).
Device Management Portal.

There are two main ways to interact with an API:

Command line utility, or cURL. To find the command line:
- On Mac: Search for and open the Terminal application.
- On Windows: Go to Start > Windows System > Command Prompt.
- On Linux: Use Ctrl+Alt+T, or search for and open the Terminal application.
Third-party interface, like Postman (Mac and Windows) or Paw3 (Mac only).

Concepts

Requests

When you make a request using an API, HTTP provides the following methods:

GET: retrieve information.
POST: set or send new information.
PUT: change existing information.
DELETE : remove information.

The request may occasionally be referred to as a call to an interface.

There is usually a response from the server, either a block of information formatted as JSON, or a status code.

Note: Some API operations are restricted to certain account types. If you send a request that you're not authorized to use, the server responds with a 403 code.

API resources

Each API resource has at least one uniform resource identifier (URI) associated with it. The URIs follow a predictable and hierarchical structure that provides resource relations.

Device ID

To use the APIs, you must provide the Device ID, not its PSK ID. For more information, see the device identity section.

cURL requests

cURL is a utility that lets you make HTTP requests through your command line. Refer to the cURL documentation for more information on setting up and using cURL.

In our API documentation, you can see example cURL requests. The model for these requests is:

curl -X <method> https://{host}/<endpoint> \
-H 'Authorization: Bearer <api_key>' \
-H 'content-type: application/json' \
-d '{
      "name":"Device.",
      "description":"Testing."
}'

Replace <method> with GET, PUT, POST, or DELETE.

Authentication

Authenticate Device Management APIs using API keys, which you can obtain from Device Management Portal. For more information, see Access Device Management with API keys.

The APIs use bearer authentication:

Authorization: Bearer ak_272f4259b2b1470599c19bc4a473d3cb

Include this authorization token in a header in every request.

You must make all requests to the APIs over HTTPS; requests made over HTTP will redirect, and requests made without an authentication mechanism will fail.

Warning: An API key has full privileges to your account, so keep it secret. The full API key is used for authorization only. Never put it in your request as part of the URI or a query parameter, as it may then be visible in network server logs. If you think your API key was compromised, contact us.

Request ID

The server assigns a unique and permanent request ID to each API request. A single request always returns the same ID:

In each response, in the X-Request-ID header.
In an error response, in the request_id field (in addition to the X-Request-ID header).

The maximum length of an ID is 32 characters.

Tip: When contacting support, please provide the request ID.

Pagination: Viewing results

Resources support bulk GET actions using the list operation. The list API uses common arguments. All parameters are optional.

Argument	Description
`limit`	The number of results to return. Default: 50, minimum: 2, maximum: 1000.
`after`	The entity ID after which to start fetching.
`order`	The order of the records to return. Available values are ASC and DESC. The default value is ASC.
`has_more`	Indicates whether there are more results for you to fetch in the next page.
`include`	Comma-separated additional data to return. Currently supported: `total_count`.

Filtering results

Filters allow you to sort returned results. Refer to the Service API references to see which operations support filtering. Define the field filter by adding a double underscore (__) to the end of the field name concatenated with the operator.

Filter operators:

Operator	Usage
Equal	`__eq`
Not equal	`__neq`
Less or equal	`__lte`
Greater or equal	`__gte`
Include records	`__in`
Exclude records	`__nin`

An example request:

GET /v3/users?status__eq=ACTIVE

An example response:

{
    "object": "list",             // API Resource name.
    "limit": "<request_limit>",   // From request (range: 2-1000), or equal to total_count.
    "after": "<request_after>",   // Entity ID, from request or null,
                                  // For example, 2d238a89038b4ddb84699dd36a901063
    "order": "<request_order>",   // ASC or DESC. Default: ASC.
    "data": [
        // < entity >,
        // <   ...  >,
        // < entity >
    ]
}

To filter date-time fields, specify a filter value using RFC3339 (for example, 2016-11-30T16:25:12.1234Z) or a truncated format (for example, 20161130T162512Z).

Backward compatibility

To minimize the risk of breaking your integration:

Ignore unexpected fields from responses.
Don't rely on the order of fields in the responses.
Expect new API resources and types to emerge.

Documentation