# Dx-Core API for ThingPark Enterprise
DX-Core API is now a legacy API
Things Management API (opens new window) should be preferred.
Welcome to the ThingPark Enterprise - Dx-Core API reference documentation. The purpose of this API is to provide the best experience for all developers who intend to interface with ThingPark OS or ThingPark Wireless for party, user, subscription, application, device, base station, alarm management or downlink sending.
# API reference
The API reference is available on Swagger-UI.
To use the API from your application, you can generate client code using the API’s OpenAPI contract in YAML format available on the Swagger-UI.
# 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
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 (opens new window) 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 (opens new window), 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. To use the API, you must first get an access token, providing access to specific endpoints of the API, until it expires or is revoked.
To get an access token, the token endpoint should be called providing a valid client ID and client secret of a service account. See Quickstart (opens new window) in the ThingPark Wireless API Documentation.
Using an access token issued by the GET /oauth/token endpoint of DX-ADMIN
is still possible for compatibility. Using service account's credentials
as described above should be preferred.
Every call to a DX API must specify the Authorization HTTP header. The value of this
header must be set to Bearer <token>, 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/123GET /deviceAlarms/678000/acks
# Unique resource identifier
Only one URI is defined for the same resource or collection of resources. Accessing potentially same resource 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.