menu arrow_back close search On Github

Collections

  1. Home
  2. REST API
  3. Collections

Collections makes it easier to manage large and small sets of devices and to group devices into logical groups. By default you’ll have a single collection where all devices you create will be put into. A device can’t be a member of more than one collection at a time.

Devices can be shared between team members by having a shared collection owned by the team.

List of collections: /collections

The list of collections contains a list of all collections you have access to, both read-only and read-write (ie you can administer). New collections can be created by POSTing to this resource.

$ curl -HX-API-Token:${TOKEN} https://api.nbiot.telenor.io/collections
{
  "collections": [
    {
      "collectionId": "17dh0cf43jfgl8",
      "teamId": "17dh0cf43jfgl8",
      "tags": {
        "name": "My default collection"
      }
    }
  ]
}

Creating a new collection

Send a POST request to the /collections resource to create a new collection. There is no required fields so an empty JSON object is sufficient. It is recommended to use the tags resource and add an attribute named name to identify the collection. The console will use this attribute when displaying the list of collections.

$ curl -HX-API-Token:${TOKEN} -XPOST -d'{"tags":{"name": "My first collection"}}' \
    https://api.nbiot.telenor.io/collections
{
  "collectionId": "17dh0cf43jfgli",
  "teamId": "17dh0cf43jfgl8",
  "tags": {
    "name": "My first collection"
  }
}

Collection detail: /collections/{collectionId}

Details for each collection is available at the detail resource:

curl -HX-API-Token:${TOKEN} https://api.nbiot.telenor.io/collections/17dh0cf43jfgli
{
  "collectionId": "17dh0cf43jfgli",
  "teamId": "17dh0cf43jfgl8",
  "tags": {
    "name": "My first collection"
  }
}

Updating a collection

Use PATCH to update the collection. You must be the administrator of the team owning the collection and and administrator of the team you assign the collection to if you change the ownership of an collection.

$ curl -HX-API-Token:${TOKEN} -XPATCH -d'{"teamId": "17dh0cf43jfgl9"}' \
    https://api.nbiot.telenor.io/collections/17dh0cf43jfgli
{
  "collectionId": "17dh0cf43jfgli",
  "teamId": "17dh0cf43jfgl9",
  "tags": {
    "name": "My first collection"
  }
}

The server responds with the updated collection when successful.

Removing a collection

Use DELETE to remove a collection. The collection can’t contain any devices or outputs when it is deleted.

$ curl -HX-API-Token:${TOKEN} -XDELETE https://api.nbiot.telenor.io/collections/17dh0cf43jfgli

The server responds with a 204 NO CONTENT when a collection is removed.

Collection data stream: /collections/{collectionId}/from

The server provides a WebSocket to monitor the output (ie the upstream data) of the devices. All data transmitted by the devices will be forwarded to the WebSocket.

The data sent by the devices are included in the field payload and is base64-encoded.

{
  "device": {
    "deviceId":"17dh0cf43jfgl8",
    "collectionId":"17dh0cf43jfgli",
    "imei":"111222333444",
    "imsi":"123456789",
    "tags":{
      "name":"My first device"
    }
  },
  "payload":"WXVwIHRoaXMgaXMgdGhlIHBheWxvYWQ=",
  "received":1538163685141
}

At regular intervals the server will send a keepAlive message on the WebSocket:

{
  "keepAlive": true
}

The keep-alive message will only be sent if there has been no data for 30s.

API key as query parameter

Most WebSocket libraries doesn’t support headers in requests; the API token can be supplied through the api_token parameter. The API token must be readonly.

Downstream data: /collections/{collectionId}/to

If you want to send data to the devices POST to this resource. Both the port number and the payload fields are required.

{
  "port": <port number>,
  "payload": "<base 64 encoded bytes>"
}

Note that the devices must be listening on the specified port to receive the message.

Response

The response contains an array of error messages. The array might be empty. The sent and failed fields shows how many messages have been sent and how many messages failed to send.

{
  "errors": [
    {
      "deviceId": "<the device ID>",
      "message": "<error message>"
    }
  ],
  "sent": <number of messages sent>,
  "failed": <number of failed messages>
}
Edit this page