REST API

Overview of the Eliona REST APIThe Eliona REST API enables uniform access to the resources and data of an Eliona environment. The API description is available in the widely used format OpenAPI and can therefore be reused in many different ways.

Eliona API

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

Access and authentication

The Eliona API can be accessed via the URL path /api/v2 If the URL for Eliona is, for example, https://meine.eliona.domain, then the API can be reached at the following URL:

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

An API key must be used for authentication. This is issued per application by the Eliona administrator and may have an expiration date. To create one, it must be known which endpoints of the API are needed and whether read or write access is required.The API key must be included in the HTTP header of the request as X-Api-Key GET https://meine.eliona.domain/api/v2/assets/158X-Api-Key: {{key}}

Postman Collection with examples

A Postman collection with several request examples is available for easy API testing. You can import the file postman_collection.json directly into Postman via the following URL. Before using the collection, make sure to update the variables api-server and read-write-token according to your environment.

https://raw.githubusercontent.com/eliona-smart-building-assistant/eliona-api/refs/heads/main/examples/postman-collection.json

Clients for access to the API

Clients for different programming languages

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

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

Here is an example command 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 provided via GitHub.

Postman: Importing the API description

The OpenAPI description of the Eliona REST interface can be imported into Postman. This makes all endpoints 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

Import URL for workspaceAfter the OpenAPI file has been imported, all endpoints are available. For the API to be used, the API key must be entered under Authorization and the respective base URL under Variables.

Mock for API tests

For testing with the API, an appropriate Eliona mock is available. It can be used independently of a full Eliona environment. The mock provides a complete API implementation and a simplified Eliona database via a Docker network. The appropriate docker-compose.yml and the database definition are provided via GitHub:

PreviousReport a bug NextEngineering

Was this helpful?