# ThingPark X Location Engine API - Key Management module
Welcome to the ThingPark X Location Engine Binder API reference documentation. The purpose of this API is to provide the best experience for all developers who intend to interface with ThingPark geolocation features.
TPX LE Key Management module enables configuration of Binders for Operators on the ThingPark X Location Engine Solution. The module has 2 REST endpoint contracts, one capturing 3 specific endpoints for external Operators and the other capturing 5 endpoints, with 2 specific endpoints for internal access. The module provides a Binder endpoint, to retrieve a specific or list of all available Binder configurations available on the platform. This provides details on the configuration schema to create specific Binder Connections for each Operator. The BinderConnection endpoint paves way for Operators to add specific keys on the platform adhering to the schema reviewed earlier. BinderConnections are created by SubscriberID and on creation, the keys provided are masked and a signed TPX LE JWT encapsulating the SubscriberID is provided. This token is to be provided by the Operator on each Uplink message for message validation. There is an Events endpoint, that is specifically for auditing purposes, where an Operator can view all operations on Binders by SubscriberID. The module provides also an endpoint to retrieve customer-defined geolocation connection, including customer resolution-engine API key (ex. google API key), etc.
The internal endpoints are for access by internal modules in TPX LE. The first endpoint is used by OperatorInterface to retrieve BinderConfigurations by BinderID. The difference is that the BinderConfigurations returned in this case contain all the necessary keys specific to the BinderID and the RSA key pairs required to decrypt data and verify JWT signatures. The second endpoint is used by License Manager module to retrieve a signed TPX LE JWT given a specific subscriberID.
In order to get acquainted with the API, you can use the convenient online client Swagger-UI.
To use the API from your application, you can generate client code using the API’s OpenAPI contract.
# ThingPark X Location Engine Modules
To discover all the TPX LE modules:
Binder
Connector
LIM
Tracker Command
Key Management
Alarm Config
Notification
Firmware Update
Driver
Profile Management
Geolocation
# 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.
Dx-Admin API
Dx-Core API
Dx-Maker API
Dx-Location API
Tpx IoT-Flow API
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.
# Important note
DX Dataflow API is now deprecated. For data processing and dataflow management (drivers and connectors), you can now use IoT-Flow
# 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
TPX LE 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 TPX LE 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.
TPX LE APIs OpenAPI/Swagger contracts are based on the version 2.0 of the OpenAPI specification.
# Token-based authentication
TPX LE 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 |
| 403 | Forbidden -- 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.