Overview

Energomonitor API is a standard RESTful API. This section discusses its technical aspects.

Access

The current version of the API can be accessed via HTTPS using the following URL:

All resource URLs in the documentation are relative to this URL. Plain HTTP access is not supported.

Authentication

All requests to the API must be authenticated with an access token, specified using the Authorization HTTP header:

Authorization: Bearer mKKVFYdCjTgs74abyyTH4Mtt7Az4yJ

You can generate the token in the Energomonitor application or using the /authorizations API endpoint (which doesn’t require token authentication itself).

Note

The token always authorizes access to a specific list of user’s resources (e.g. feeds). When the list of resources gets extended (e.g. the user installs new Homebase and a new feed is created), you’ll need to generate a new token.

Note

The token has a fixed expiration time for security reasons. You’ll probably want to save the expiration time when a token is generated and generate a new token when the current one gets expired.

Data formats

All data sent and received by the API is in JSON.

Client errors

All client errors (such as malformed requests or validation errors) are reported using 4xx HTTP status codes. The error response contains an object with a message property which describes the error.

The API uses the following error status codes:

Code Cause(s)
400 Invalid request (e.g. missing property or invalid property value).
401 Missing or invalid credentials, missing or invalid token, expired token, unauthorized access to a resource.
403 Attempt to create an authorization to a resource the user is not authorized to access.
404 Resource not found (e.g. wrong feed ID).
429 Attempt to go over the rate limit.

Rate limiting

There is currently a limit of 10 requests/s per IP address. When you go over the limit, the responses get delayed. If you press further, the API will start to return responses with 429 HTTP status code.

CORS

The API supports Cross Origin Resource Sharing (CORS). It allows requests from any origin.

Versioning

The API is versioned. The current version is 1, which is expressed as /v1 in the API URL. In the future, we may release new versions of the API which may not be backward-compatible. Within each API version, we will perform only backward-compatible changes.

In general, changes that add functionality (e.g. adding a new resource, request parameter, or object property) are considered compatible. Changes that change, rename, or delete existing functionality are considered incompatible.