Skip to main content
Skip table of contents

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.