Apio IoT API

Introduction

The Apio IoT API is based on HTTP and REST, it exposes resource-oriented URLs, accepts JSON-encoded bodies (with a few documented exceptions), returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs, such as POST, GET and PUT.

This means you can use any HTTP/REST client or library to interact with it, as long as you provide the correct parameters described in this documentation.

Authentication

Most of the functionalities requires authentication, which comes in two forms:

• Bearer Tokens: Users can provide their credentials at the authenticate endpoint and, if those credentials are correct, the API will provide in return a bearer token which can be used to authenticate further requests.
• API Keys: applications and devices can provide API Keys created by users.

Bearer Token

Once an authentication token was obtained by the authenticate endpoint, the token can be used to authenticate subsequent requests.

The token must be provided in the Authorization header using the following syntax and replacing <mytoken> with the actual token.

Authorization: bearer <token>

API Key

API Keys can be created using the API Key endpoint, remember that the value of the apikey is showed to you only in the response of this endpoint, after that you have no way to retrieve it, since we do not store its value in clear.

The API key must be provided in the Authorization header using the following syntax and replacing <mykey> with the actual api key.

Authorization: apikey <mykey>

Errors

Errors are reported using conventional HTTP status codes, hence any response with a HTTP status in the 4xx or 5xx range is an error response, while responses in the 2xx range indicate success.

Error responses also include a response body with the following form:

{
  "status":false,
  "error":{
    "name":"Unauthorized",
    "statusCode":401,
    "message":"Missing authorization header.",
    "type":"Unauthorized"
  }
}

Some errors might provide additional context in the form of a code attribute, in the error struct.

Pagination

All API resources have methods for fetching lists of items, for example you can list devices, list plants and so on. All these endpoints allow to paginate the results by using two parameters: skip and limit.

limit is used to set the number of items that should be returned in the response, while skip tells the API how many items should be skipped in the result set.

For example, passing skip=20 and limit=20 returns the items from number 21 to 40 in the collection (depending on the chosen sorting).

Sorting

As for pagination parameters, all list methods support sorting by arbitrary attributes.

The sortby parameter tells the api which field should be used for sorting, while sortorder can have only two possible values: ASC for ascending sorting and DESC for descending sorting.

Request IDs

Each API response has a request identifier. This identifier can be found in the response headers under the header X-Request-Id. This can be useful when contacting support for easier issue identification.