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:
- DX Admin API for token management and other DX platform administration features
- DX Core API for account management, offer subscription, device and base station provisioning
- DX Maker API for device pre-provisioning and management at manufacturer stage
- DX Dataflow API for data processing and dataflow management (drivers and connectors
- DX Location API for integration with ThingPark geolocation solutions (solvers and applications)
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:
- OpenAPI/Swagger contracts for standard API description
- Token-based authentication through an OAuth2 workflow
- Content negotiation through HTTP headers
- Standard HTTP verbs to indicate actions on resources
- Standard HTTP response codes to indicate success of errors
- Identifier conventions to find resources more intuitively
- Examples in every DX API reference documentation
- Versioning to facilitate client-side migration
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
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:
https://dx-api.thingpark.com/core/v120
In order to always use the latest version of a DX API, the URL with 'latest’ version can also be used:
https://dx-api.thingpark.com/core/latest
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.