API - Application programming interface

The thingsHub REST-API enables you to integrate IoT devices using system from your IT landscape. This API is a RESTful, resource-oriented API that allows you to programmatically provision devices, create and modify device drivers, and configure integration.

Each endpoint uses standard HTTP verbs like GET and POST, and will return standard HTTP response codes to indicate request status or errors.

We built the API to accept and return JSON in all responses, including errors.

API Functionality

Using the API you can:

Authorize against thingsHub
Create and delete API keys
Create, read, update, delete network connections, devices, integrations, data tables, etc.
Push into the tenant’s internal driver registry
and much more

Authentication

Authenticate your calls to the API by providing an access token in your requests. Each access token is associated with a logged in thingsHub user session. Access tokens do expire with the user session.

In the examples in this documentation, we use bearer auth:

JS

curl -X GET "https://demo.thingshub.smartmakers.de/api/v3/devices"
     -H "Authorization: Bearer <ACCESS_TOKEN>"

All requests must be made over HTTPS or they will fail. API requests that don’t contain authentication will also fail.

Generating a user session-based access token

Access tokens are obtained by performing an authorization using the "auth/token" endpoint:

CODE

curl -X POST 'https://demo.thingshub.smartmakers.de/api/v3/auth/token'
     -H 'Content-Type: application/json' 
     -d '{"password":"<YOUR_USERS_PASSWORD>","username":"<YOUR_USERS_NAME>"}"

When successful, this endpoint return a status of 200 OK and the generated access token as field "token":

CODE

{
    "User": {
        "country": "",
        "created_at": "2018-10-12T14:22:34.796848Z",
        "email": "",
        "full_name": "",
        "id": 1,
        "last_login_at": "2018-11-15T21:28:10.517042266Z",
        "password": "",
        "updated_at": "2018-11-15T21:28:10.51943005Z",
        "username": "admin"
    },
    "expires": "2018-11-22T21:28:10.505019278Z",
    "token": "f4maabU0behdKcMTOPX_1BB08RpEfM0fcfdkZYNEaIc="
}

Error Codes and Messages

Response Codes

The API will attempt to return HTTP status codes for every request.

Code	Text	Description
200	OK	The request was completed successfully.
201	Created	The resources was created as requested.
400	Bad Request	The request is invalid, contains malformed data, or otherwise cannot be served. The reasons for invalid requests can vary by endpoint. An accompanying message will provide detail about the reason for failure.
401	Unauthorized	The request doesn’t have a valid API access token. Verify your token is correct and re-try the request.
403	Forbidden	The user is correctly logged-in, but the requested operation is not allowed for this user.
404	Not Found	Potential causes: The URI requested is invalid The requested resource, such as a specific source, doesn’t exist Method is not allowed by the endpoint
500	Internal Server Error	An error happened inside one of the services that is unexpected and could not be handled appropriately.
503	Service Unavailable	This error will be returned if one if the thingsHub’s internal services is unavailable.

Error Objects

If an request cannot be handled successfully (indicated by an HTML response code in the range of 4xx or 5xx), along with the response code itself in the response header an error object is returned in the response body. The error messages as JSON objects of the following structure:

CODE

{
    "code": 400,
    "error": "invalid credentials"
}

The code is always equal to the the HTML return code, while error gives a user-readable explanation of the cause of the error. The text in error messages will vary by root cause and endpoint. Each endpoint section contains a roll-up of the errors specific to that endpoint. Refer to the documentation for the endpoint for specifics on errors, their possible causes, and the messages the API will return. Note that the list of error messages is not exhaustive and can be parametric, so prefer not do not check for the specific spelling of an error message.