Operational Support System

The OSS has several interfaces that can be accessed through APIs.

A RESTful Web services architecture follows basic design principles:

• It exposes a tree of resources via URI
• It is stateless. Each request from any client contains all the information necessary to service the request, and session state is held in the client.
• A resource is represented by an hypermedia type, for example JSON
• It uses HTTP methods explicitly (GET, POST, PUT, DELETE, …) and other HTTP standards
• hypertext links to reference state
• hypertext links to reference-related resources

The API version level is requested by the client using the accept HTTP header, for example here with API v1:

Accept: application/vnd.kerlink.iot-v1+json

GET http://kerlink.fr/oss/rest/application/customers/198/fleets?page=3&PageSize=40

This web service allows to get the page number 3 of the list of fleets of the customer 198.

The list of possible verbs is : GET, POST, PUT, DELETE, PATCH

• POST: creates a new resource.
• GET: gets a resource.
• PUT: updates an existing resource.
• DELETE: deletes a resource.
• PATCH: updates a subset of fields of an existing resource.

These examples use the command-line program curl to make HTTP requests.

If you want to test, you could also use mockable.io or any other tool of your choice.

The use of the API is bound to a fresh token. Here is how you can request for a new token:

curl -s 'http://wanesyserver.tld/oss/application/login' \
  -H 'Accept: application/vnd.kerlink.iot-v1+json' \
  -X POST \
  -d '{"login":"jdoe","password":"P@ssW0rd5ecRe7"}' \
  -H 'Content-Type: application/vnd.kerlink.iot-v1+json' \
  | jq .

Here jq is used to prettify the JSON output so that it is readable and indented:

{
  "expiredDate": 1500537180050,
  "tokenType": "Bearer",
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJzdXBlcmFkbW ... n6i5WboHR-I"
}

curl -s 'http://wanesyserver.tld/oss/application/customers' \
  -H 'Accept: application/vnd.kerlink.iot-v1+json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJzdXBlcmFkbW ... n6i5WboHR-I' \
  | jq .

Result:

{
  "count": 2,
  "pageSize": 50,
  "page": 1,
  "totalCount": 2,
  "list": [
    {
      "id": 130,
      ...
    }
  ],
  "nbPages": 1
}

$ curl -s 'https://wanesyserver.tld/oss/application/authenticatedUser' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJzdXBlcmFkbW ... n6i5WboHR-I' \
  -H 'Content-Type: application/vnd.kerlink.iot-v1+json;charset=UTF-8' \
  -H 'Accept: application/json, text/plain, */*' \
  | jq  '.links[] | select(.rel=="customer") | .href'

The jq filter is used to show only customer ID information. In fact, it will display the href value for all links objects for which the rel key has the customer value.

Example result with customer ID number 23:

"/application/customers/23"

Not all fields in TxMessageDto are required when creating a new TX message. The actual parameters to send are:

• port: integer, LoRaWAN application port number
• payload: string, data payload, either encoded as an hex string or binary data in base64
• ack: boolean, whether the TX message should be acknowledged (confirmed data transfer)
• contentType: enum { TEXT, HEXA }, describes how the payload is encoded
• maxRetry: integer (optional), maximum number of transmission attempts. Only required if ack is true.
• timeToLive: integer (optional), time to live. Only required if ack is true.

No other parameter is supported.