NAV Navbar

DX API Platform

The ThingPark DX API Platform is the central access point to discover and explore ThingPark DX APIs.
A DX API intends to expose features of ThingPark OS, ThingPark Wireless, ThingPark X, ThingPark Location and other ThingPark products through a REST “Developer Experience” API, i.e. with a strong focus on simplicity, best practices and standards.

Currently the DX API Platform exposes the following DX APIs:

While every DX API has its own reference documentation, which can be accessed using one of the links above, the current page intends to provide guidelines which are common to all DX APIs.

General principles

DX APIs embrace commonly accepted best practices of REST (HTTP) APIs, including:

DX APIs are also stateless and do not rely on any cookies, in order to provide ease-of-use and best scalability.

OpenAPI/Swagger contracts

Every DX API is described through an OpenAPI contract, formerly known as Swagger contract. OpenAPI is the most-adopted contract format for REST APIs, allowing developers to describe and share API endpoints, parameters, responses, errors, etc, regardless of client-side or server-side technologies. Furthermore, there is a rich ecosystem of tools compatible with the OpenAPI/Swagger contract, such as the Swagger tooling, which allow for example developers go get quickly started with DX APIs by generating client code in many development languages as well as using out-of-the-box viewers and editors.

DX APIs OpenAPI/Swagger contracts are based on the version 2.0 of the OpenAPI specification.

Token-based authentication

DX APIs rely on an OAuth2 authorization workflow: in order to use the API, one must first get an access token, providing access to specific endpoints of the API, until it expires or it is revoked.

In order to generate a new token, the GET /oauth/token endpoint of the DX Admin API, as per the OAuth2 security standard, must be used. When generating a token, it is necessary to provide the target profile (i.e. pointing to a ThingPark server instance) and the credentials of a ThingPark user account (either an admin or a subscriber user account). For more convenience, the Get Started page can also be used.

While it is valid, a token is associated with one or multiple scopes. A scope is a group of permissions (creation, update, etc) over a set of resources, granted by a ThingPark role (such as OPERATOR, VENDOR, SUBSCRIBER or SUPPLIER). Scopes are defined during token generation depending on provided ThingPark profile and ThingPark credentials. Each endpoint on a DX API requires the presence of one or more scopes in order to be used; scopes allowed per endpoint are specified in the reference documentation of each DX API.

With the exception of the DX Admin API which is used to generate tokens, every call to a DX API must specify the Authorization HTTP header. The value of this header must be set to ‘Bearer ’, as per the OAuth2 security standard. A typical request to a DX API endpoint should therefore specify the HTTP header below:

Authorization: Bearer <your_generated_token>

Content negotiation

Message formats for both requests and responses can be negotiated respectively with the Content-Type and Accept HTTP headers. Currently both application/json and application/xml formats can be specified. A typical request to a DX API endpoint should therefore specify the HTTP headers below:

Content-Type: application/json
Accept: application/json

HTTP verbs

CRUD actions on resources are indicated through HTTP verbs. DX APIs rely on the following HTTP verbs: GET, POST, PUT and DELETE. OPTIONS can also be used in particular for AJAX requests. Currently PATCH is not implemented for partial updates. Below is a description of expected behaviour for each HTTP verb

HTTP verb Collection: /users Single resource: /users/123
GET Collection retrieval
Possible parameters: header, query
Response: the collection of full or partial resource bodies, with HTTP response code 200
Resource retrieval
Possible parameters: header
Response: the full resource body, with HTTP response code 200
POST Resource creation
Possible parameters: header, body
Response: the full created resource body, with HTTP response code 201
PUT - Resource update
Possible parameters: header, body
Response: the full updated resource body, with HTTP response code 200
DELETE - Resource deletion
Possible parameters: header
Response: empty body, with HTTP response code 204

HTTP response codes

Success or failure of requested operations are returned through HTTP response codes. In particular, DX APIs use HTTP response codes below.

Code Description
200 OK – Successful retrieval or update request
201 Created – Successful creation request
204 No Content – Successful deletion request
400 Bad Request – Your request has incorrect parameters
401 Permission Denied – You do not have the rights to access the specified resource
404 Not Found – The specified resource could not be found
405 Not Allowed – The resource cannot be accessed with this URI or method
500 Internal Server Error – We had a problem on our server, please report it

Identifier conventions

DX APIs embrace REST resource-oriented design, and rely on conventions presented hereafter to make finding and performing actions on resources more intuitive.

Collection of resources

Collections of resources are identified with plural nouns.

GET /users

Child resources

Resources are identified through their parents. In particular, single resources are identified through their parent collections.

GET /users/123
GET /deviceAlarms/678000/acks

Unique resource identifier

Only one URI is defined for the same resource or collection of resources. Accessing potentially same resources through multiple URIs is avoided, as it makes APIs less intuitive.

Resource inheritance

Resource inheritance is supported by the OpenAPI format and is therefore used whenever attributes are shared by resources. For example DeviceAlarm and BaseStationAlarm resources both inherit the Alarm resource.

Non-CRUD actions

For non-CRUD actions, verbs in resource identifiers are avoided, e.g. POST /sendDownlinkMessage is not used. Instead, DX APIs expose everything as resources, e.g. POST /downlinkMessages means creating a new downlink message resource, i.e. sending a downlink.

Consistent case

DX APIs rely on camel case for all identifiers (resources, attributes, parameters). The only exception is the DX Admin API which uses snake case as per the OAuth2 standard.

Request/response examples

Examples are key to the understanding of an API, therefore every DX API documentation provides examples of requests and responses for at least basic use cases. These examples can be copied and modified to fit your needs, for example inside the Swagger-UI online client, thus enabling quick onboarding for new comers.

Examples also help to understand specificities of the different endpoints. For example, while most attributes are required during a resource creation (POST request), sometimes only modified attributes should be specified during a resource update (PUT request). Also, ref and id attributes generally can’t be updated.

Versioning and migrations

Every new version of a DX API is released with a distinct URL specifying that version’s number, for example for version 1.2.0:

In order to always use the latest version of a DX API, the URL with 'latest’ version can also be used:

Whenever a new major version is released, DX API users registered on the Actility’s developer list are notified in order to migrate to this new version. Older versions become deprecated and are usually deactivated after an average delay of 2 months.