Best practices

General recommendations

Please implement a custom user agent header for your application (https://www.rfc-editor.org/rfc/rfc9110.html#name-user-agent). This is quite helpful for troubleshooting purposes. If you want to update the state of your devices on your UI regularly or immediately after the device state changed please have a look at our eventing endpoints.

By using SSE subscriptions you can avoid to implement a regular polling and you always receive the latest device state automatically.

Eventing

There are two available routes to subscribe to our SSE-channels. If you intend to get status updates for every device in your account you should use the /v1/devices/all/events route in order to minimize the number of open connections. The number of parallel opened connections is limited per IP and client. Excessive usage will result in HTTP 503 error (rate limiting).

If you only intend to get updates for a single device you can of course use the subscription via /v1/devices/{deviceId}/events.

Token retrieval

After successful token retrieval please use the refresh token to obtain a new access token after expiration (https://www.rfc-editor.org/rfc/rfc6749.html#section-6); retrieving too many parallel access tokens for one account per client will lead to a deactivation of the client credentials as the number of access tokens per client is limited.

Please do not forget to implement a mechanism for reinitiating a login if refresh tokens or access tokens are invalid or expired. We recommend to use the logout endpoint in order to invalidate unnecessary tokens.

Rate limiting

As stated above certain elements of the API have limitations. The number of access tokens per client and customer is limited. After reaching that limit further token retrieval is not possible. The number of REST-requests and SSE subscriptions per IP is limited and will lead to HTTP 503 if they exceed the limits.