Lhings API Documentation

Lhings provides a HTTP API to allow connecting devices to it. The API is composed of a set of web services that we divide in the following categories:

  • Device API: contains the services that have to do with the lifecycle of the device.
  • Management API: contains the services that allow to manage the devices and rules of your Lhings account. This API provides an HTTP interface to most of the features the Lhings web application provides.
  • Data API: this API provides the way to store data from your devices in Lhings and retrieve its values.

You can also check the API reference documentation

How to use the API

Security and authentication

The API can only be accessed using HTTPS protocol. Any call to the API must be authenticated. This is done by providing the API key of the user performing the request in a X-Api-Key HTTP header, like in this example:

X-Api-Key: 7df780d2-e6ae-44f1-ba73-86d1467b65d8

Content-type and encoding

Some of the services require some information. This information is always sent in the request body, in JSON format, and encoded in UTF-8. Check the reference documentation of each service for details. For these services, do not forget to add the header Content-type: application/json.

API call results

Most of the API calls will return an HTTP status 200 upon success. In case there is any error related to the API, it will return an error response with an HTTP status 457. Body of responses will provide more details about the nature of the error. The response will be in JSON format and will be like this one:

{"responseStatus":404,"message":"Device not found"}

The responseStatus will be a number which meaning will losely follow the HTTP specification. For example, a 404 responseStatus will mean Not found. What has been not found is something that will depend on the context. For instance, if the web service sends an action to a device, likely Not found will refer to that device, meaning it does not exist in Lhings. Anyway, message will always contain information about the error to help the developer pinpoint its cause.

API rate limits

The usage of the API is subject to some rate limits to avoid abuse. The rate at which requests can be done to the API cannot be higher than two limits, an hourly one and a minute one. This is done to allow for small burst of requests from time to time while enforcing tighter limits in extended periods of time. For example, suppose the hourly limit is 600 requests and the limit per minute is 300. This will mean than although on average you are not allowed to make more than 10 requests per minute, you can make up to 300 requests a given minute, maximum twice an hour.

Whenever you hit the rate limit, the server will respond with an HTTP status 429 "Too many requests". You won't be able to perform any more requests until time passes by and you are out of the rate limit again.

During the beta stage this limits may change, but you should be able to perform of the order of hundreds of requests per hour.

Back to top