REST API
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 API's description is in the widely used OpenAPI format and can therefore be reused in various ways.
The Eliona App SDK provides pre-built libraries for different programming languages to access Eliona via the API.
Access and Authentication
The Eliona API can be reached via the URL path /api/v2. For example, if the URL for Eliona is https://my.eliona.domain, the API is reached via the following URL:
https://my.eliona.domain/api/v2
An API key is used for authentication. This is issued per application by the Eliona administrator and can have an expiration date. To create it, it must be known which API endpoints are needed and whether read or write access should be granted. The API key must be supplied in the HTTP header of the call as X-Api-Key:
GET https://my.eliona.domain/api/v2/assets/158
X-Api-Key: {{key}}Postman Collection with Examples
A Postman collection with multiple request examples is available for easy API testing. You can import the postman_collection.json file directly into Postman using the following URL. Before using the collection, make sure you update the api-server and read-write-token variables to match your environment.
Clients for API Access
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. Various methods are available for generation. It is recommended to use the provided Docker image. The latest version of the OpenAPI description is referenced for this:
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](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 always being 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, import the following URL into Postman:
https://raw.githubusercontent.com/eliona-smart-building-assistant/eliona-api/main/openapi.yaml
Import URL for Workspace After the OpenAPI file has been imported, all endpoints are available. To use the API, the API key must be entered under the "Authorization" section and the respective base URL under "Variables".
Mock for API Tests
A corresponding Eliona mock is available for testing the API. This can be used independently of a complete Eliona environment. The mock provides a complete API implementation and a simplified Eliona database using a Docker network. The appropriate docker-compose.yml and the database definition are provided via GitHub:
Last updated