Control plane

The control plane APIs handle the management of your LoRaWAN® wireless network. The quickstart page shows you how to get started with the control plane APIs.

Base stations API

The Base stations API allows to deploy your LoRaWAN® wireless network.

Devices and connections API

The Devices and connections API allows to manage your devices, relays, multicast groups and connections.

info

ThingPark X IoT Flow connections are managed with the DX Core API.

To get the full description of the API operations available for ThingPark X IOT Flow connection, see the DX Core API documentation of your platform:

ThingPark Community
ThingPark Enterprise SaaS EU
ThingPark Enterprise SaaS AU
ThingPark Enterprise SaaS US
Self-hosted ThingPark Enterprise: https://<domain>/thingpark/dx/core/latest/swagger-ui.html#/Connection where <domain> is the hostname/IP address of your self-hosted ThingPark Enterprise

Notifications API

The Notifications API provides the result of asynchronous tasks such as device mass import operations.

Administration API

The Administration API manages user accounts, service accounts and domains.

Common behavior

All control plane APIs share the common behavior described in this section.

Authentication

Authentication relies on OAuth v2. All requests should include a valid Bearer token in the Authorization HTTP header. The Bearer token is an OAuth v2 access token issued using the Client Credentials Grant.

The URL of the Oauth token endpoint is https://PLATFORM-HOSTNAME/users-auth/protocol/openid-connect/token.

To get an access token, a POST request should be sent on the token endpoint providing a client ID and client secret in the body.

The client ID and client secret are properties of a service account. Service accounts are managed by admin on the ThingPark user interface.

The HTTP response is a JSON object containing the following properties:

access_token: the access token,
expires_in: the number of seconds that the access token will be valid.

The access token is usually valid for 5 minutes. When the token is about to expire, the same request should be replayed to get a fresh one.

POST /users-auth/protocol/openid-connect/token HTTP/1.1
Host: PLATFORM-HOSTNAME
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=SERVICE-ACCOUNT-CLIENT-ID
&client_secret=SERVICE-ACCOUNT-CLIENT-SECRET

HTTP/1.1 200 OK
Content-Type: application/json

{"access_token":"...","expires_in":300,"refresh_expires_in":0,"token_type":"Bearer","not-before-policy":0,"scope":"email profile"}

See quickstart for more details.

HTTP Verbs

According to REST conventions, HTTP verbs are used to achieve the following actions:

Verb	Description
`GET`	Retrieve a resource
`POST`	Create a resource
`PUT`	Edit a resource
`DELETE`	Delete a resource

Cookies

ThingPark Wireless REST API uses cookies. A user-agent implementing the RFC-6265 (HTTP State Management Mechanism) should be used to ensure that Set-Cookie HTTP headers present in responses are handled.

See the cookies section on each REST API documentation to have the list of used cookie names.

Resource creation

When a resource is created by a POST request, the response code is 201 (Created) and the response body is the representation of the created resource. A Location header is also present in the response with the URL of the created resource as value.

For example the given request create a device.

POST /thingpark/wireless/rest/subscriptions/mine/devices HTTP/1.1
Host: XXX
Authorization: Bearer ...
Content-Length: 322
Accept: application/json
Content-Type: application/json

{
   "connectivity":"LORAWAN",
   "activation":"OTAA",
   "appEUI":"ACDE48234567ABCD",
   "EUI":"ACDE48234567ABCD",
   "model":{
      "ID":"LORA/GenericA.1_ETSI_Rx2-SF12"
   },
   "appKey":"DEC499C69E9C939E413B663961636C61",
}

And the response contains the resource URL in the Location header and the resource itself in the body.

HTTP/1.1 201 Created
Date: Fri, 04 Jan 2019 14:12:49 GMT
Content-Type: application/json
Content-Length: 2014
Connection: keep-alive
Location: /thingpark/wireless/rest/subscriptions/33/devices/533011

{
   "now":1546611169519,
   "occContext":{
      "version":1,
      "lastUpdate":1546611169000,
      "who":"John Doe"
   },
   "name":"New device 533011",
   "model":{
      "commercialName":"LoRaWAN 1.0 - class A - Rx2_SF12",
      "logo":"/thingpark/wireless/rest/resources/files/logo/deviceProfile/3043",
      "typeMAC":"LoRaMAC",
      "type":"A",
      "macMajorVersion":0,
      "macMinorVersion":3,
      "ID":"LORA/GenericA.1_ETSI_Rx2-SF12"
   },
   "connectivity":"LORAWAN",
   "vendor":{
      "name":"Generic",
      "commercialName":"Generic",
      "commercialDescription":"LoRaWAN generic devices.",
      "ID":"generic",
      "logo":"/thingpark/wireless/rest/resources/files/logo/deviceVendor/313"
   },
   "creationDate":1546611169159,
   "activation":"OTAA",
   "nwAddress":null,
   "nwKey":null,
   "appKeys":null,
   "appEUI":"ACDE48234567ABCD",
   "appKey":"81CF679FFD70F5BD2B28C7A206BF4D6C",
   ...
}

Pagination

Most collection resources are paginated for performance reason. By default, the first page is delivered. If another page is available to retrieve more resources, the more property value is true. To get the next page, the same request must be made with the pageIndex query parameter incremented.

Content types

All APIs support JSON as data format for both input and output.

Content type is controlled by the Accept HTTP header for the response and Content-Type for the request. The following headers should be included in all requests.

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

Error responses

Any operation can return an error. In that case, the HTTP response have a status code greater or equal to 400. The response body may contains more details on the error cause by providing an error resource in the request body.

Usually, the schema of the error resource is the following:

Error:
   required:
      - code
      - message
   properties:
      code:
         type: integer
         format: int32
         example: '25'
      message:
         type: string
         example: unknown error

Rate Limiter

REST APIs are protected by a rate limiting mechanism against HTTP request flooding. This rate limiting mechanism uses the leaky bucket algorithm described in NGINX Rate Limiting .

REST API endpoints are classified in three categories:

HIGH_IMPACT: This category applies to endpoints with the highest level of impacts on system resources
MEDIUM_IMPACT: This category applies to endpoints with a significate impacts on system resources
LOW_IMPACT: All other endpoints that are expected to have a low impact on system resources

The category of an endpoint is documented in the OpenAPI contract using the vendor extension x-rateLimit in operation parameters. The default category is LOW_IMPACT. Therefore the vendor extension x-rateLimit is only specified for MEDIUM_IMPACT and HIGH_IMPACT categories.

paths:
  /customers:
    get:
      ...
      x-rateLimit:
         category: MEDIUM_IMPACT

Each category is associated with:

Global limit: A maximum request rate/s supported by the system without consideration for the source IP address and without consideration for the targeted domain
Source IP limit: A maximum request rate/s allowed for a given source IP address

When a limit is reached, either global or source IP, the HTTP request is rejected with a 429 Too Many Requests response.

The following configuration is defined by default for source IP limit:

Category	Source IP limit
`HIGH_IMPACT`	2r/s (burst=6 nodelay)
`MEDIUM_IMPACT`	6r/s (burst=18 nodelay)
`LOW_IMPACT`	20r/s (burst=80 nodelay)

Base stations API​

Devices and connections API​

Notifications API​

Administration API​

Common behavior​

Authentication​

HTTP Verbs​

Cookies​

Resource creation​

Pagination​

Content types​

Error responses​

Rate Limiter​