# REST API
## 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](https://www.openapis.org/) and can therefore be reused in many different ways.
[Eliona API](https://api.eliona.io/)
The [Eliona App SDK](https://doc.eliona.io/collection/referenzen/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 : {{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.
>
### Clients for access to the API
**Clients for different programming languages**
With the OpenAPI description of the interface, it is possible using [OpenAPI generators](https://openapi-generator.tech/docs/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:
>
Here is an example command to generate a client for the Go programming language.
{% code lineNumbers="true" %}
```bash
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"
```
{% endcode %}
For the programming languages Go and Python, a client is currently always updated and provided via GitHub.
{% embed url="" %}
Python client for Eliona API
{% endembed %}
{% embed url="" %}
Go client for Eliona API
{% endembed %}
**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:
>
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:
{% embed url="" %}
Eliona mock
{% endembed %}
