Current version: 1.3.1
See change log

Sensohive API Service

The Sensohive API documented using Swagger.

The specification file can be found at https://sensohive.com/docs/api/swagger.json.

The API can be explored by using the Swagger Petstore by going to http://petstore.swagger.io/?url=https://sensohive.com/docs/api/swagger.json

The API only supports JSON as the data exchange format and all times are given as Unix timestamps. In short, the API lets the user manage their Sensohive resources.

The user is authenticated by providing a simple API key, as either an HTTP header or URL query parameter. This is documented in the Swagger file. However, and API key has a number of "scopes" associated with it. These scopes are used to define, what actions a user authenticated by a given API key is permitted to do. The API presents a scope as a simple string under the section for API keys.

The following is an example of as a structure of a API key as presented by the API:

{
  "name": "ExampleKey",
  "key": "9dr9wbHC14i6fVhZ",
  "expiration": 1498730400,
  "scopes":
  [
      "readdata",
      "readdev",
      "setdevwebhook",
  ],
  "user": "John",
  "revoked": false
}

The key's name is "ExampleKey" and it expires at unix time 1498730400 (2017-06-29 13:00:00 UTC+2). It authenticates a user called "John" and has not been revoked. Under "scopes" it appears that the key has three scopes; "readdata", "readdev" and "setdevwebhook".

These three scopes allow a user to, respectevely, query the API for sensor data, see information about devices (sensor) and set up webhooks for devices. Note that while this example key is 16 characters long, API keys are automatically generated strings of 64 pseudorandom characters. Characters used in the keys are a-z, A-Z and 0-9. In short, they are mixed string of lower and upper case letters and numbers.

Table of scopes:

ScopeIntegratorsUsers
readdataNoYes
readdevYesYes
setdevuserYesNo
setdevwebhookNoYes
readusrYesNo
writeusrYesNo
delusrYesNo
readkeyYesYes
writekeyYesYes
delkeyYesYes
readwebhookNoYes
writewebhookNoYes
delwebhookNoYes
orbitmanYesYes

As of version 1.2.0 of the API, integrators are no longer able to manage webhooks, because it might potentially result in inconsistency between device and webhook owners. Instead, integrators wishing to manage webhooks should set one of their users as owner of the device and through that owner, create and manage webhooks.

Users and Integrators

As seen above, some scopes are marked as integrators only. This is because there are two types of users. Some users can be integrators, which are a form of superuser that are parents to normal users. These user types are intended for organisations that manage a number of clients or internal users. An integrator can control most aspects of their users. Some API key scopes are only relevant for integrators, since they involve user management.

Webhooks

Webhooks can be used to push data as soon as it is received from a device. This way, an API user can configure a system to listen for data. When data is received from a device, the system will send a POST request to the specified URL. The body of the request will contain the data formatted in the same way as it comes from the API. Note that the system will execute one request per data point received, so the body contains a single object and not an array.

Security
It is of course recommended that the endpoint to be called by the webhook is secured by an authentication key. This can, for example, be done by adding a query parameter to the URL. For example: https://example.org/data?key=d41d8cd98f00b204e9800998ecf8427e
Restrictions
There are a number of restrictions on webhooks. These are mostly security and stability precautions. It is possible that some of these restriction are loosened or removed in the future.

All valid IPv4 addresses that the domain's A records points to are cached and a random one is picked when the webhook executes a request.

Orbit Device Management

Version 1.1.0 of the API spec adds three new endpoints for management of the Orbit series of sensors.

An Orbit sensor collects a number of datapoints before transmitting them through the Sigfox network. The Sigfox network is limited to at most one uplink transmission every ten minutes and four downlink requests per day. An Orbit sensor has a certain configuration that influences its behaviour. Some of these parameters can be modified by messages returned to the sensors when it requests downlink data. Because of the limited nature of the Sigfox network, few parameters can be changed per downlink request. Up to two at a time in most cases. Different limits apply to individual models of the Orbit series.

The endpoint /orbit/dev/{id} shows a given Orbit sensor's active parameters as well as a list of pending changes. When a parameter update is registered in the API, it is queued up to wait for a downlink request from the Orbit sensor. When the downlink request happens, the update is sent to the sensor which will subsequently acknowledge that it has received the new parameter. At this point, the parameter update is removed from the pending-list and the active value of the sensor should now reflect the update.

To save resources, the system will change or remove pending updates instead of sending multiple or redundant messages to the sensor. This behaviour vaguely emulates the concept of idempotence with respect to the sensor rather than the state of the system.

Note that the queue is not necessarily ordered by time, as the system may prioritise or group some parameter updates for further optimisation.

Problems

If you encounter any bugs, inconsistencies, security problems, usability issues or just have questions, you are welcome to contact us at api@sensohive.com.

Best wishes,

The Sensohive Team