English

Rest API

Overview of the Eliona REST API

The Eliona REST API enables uniform access to the resources and data of an Eliona environment. The description of the API is available in the widely used OpenAPI format and can thus be reused in a variety of ways.

The Eliona App SDK enables access to Eliona via the API with pre-built libraries for different programming languages.

Access and authentication

The Eliona API can be reached via the URL path /api/v2. For example, if the URL for Eliona is https://meine.eliona.domain, then you can reach the API using the following URL:

https://meine.eliona.domain/api/v2

An API key must be used for authentication. This is issued per application by the administrator of Eliona and can be provided with an expiration date. For the creation, it must be known which endpoints of the API are required and whether read or write accesses are to be made via them. The API key must be supplied in the HTTP header of the call as an X-Api key:

GET https://meine.eliona.domain/api/v2/assets/158
X-Api-Key: {{key}}

Clients for accessing the API

Clients for different programming languages

With the OpenAPI description of the interface, it is possible to create suitable clients for a wide variety of programming languages using OpenAPI generators. Different methods are available for the generation. It is recommended to use the provided Docker image. The current version of the OpenAPI description is referenced for this purpose:

https://raw.githubusercontent.com/eliona-smart-building-assistant/eliona-api/main/openapi.yaml

Here is an example call to generate a client for the Go programming language.

docker run --rm \
     -v "${PWD}:/local" \
     openapitools/openapi-generator-cli:v6.2.1 generate \
     -g go \
     -i https://raw.githubusercontent.com/eliona-smart-building-assistant/eliona-api/main/openapi.yaml \
     -o /local \
     --additional-properties="packageName=api"

For the programming languages Go and Python, a client is currently always updated and made available via GitHub.

Postman: Import API description

The OpenAPI description of the Eliona REST interface can be imported into Postman. Thus, all endpoints are available for querying. To do this, the following URL must be imported into Postman:

https://raw.githubusercontent.com/eliona-smart-building-assistant/eliona-api/main/openapi.yaml

After the OpenAPI file has been imported, all endpoints are available. In order to use the API, the API key must be entered under Authorization and the respective base URL under Variables.

Mock for API tests

A corresponding Eliona mock is available for testing with the API. This can be used separately from a full Eliona environment. The mock provides a full API implementation and a simplified Eliona database using Docker networking. The matching docker-compose.yml and database definition is provided via GitHub:

PreviousApp SDKNextEngineering

Last updated