# REST API

## REST API

Overview of the BuildingPro Suites REST API The BuildingPro Suites REST API enables uniform access to the resources and data of an BuildingPro Suites environment. The API's description is in the widely used [OpenAPI](https://www.openapis.org/) format and can therefore be reused in various ways.

[![](https://api.eliona.io/favicon-32x32.png)BuildingPro Suites API](https://api.eliona.io/)

The [BuildingPro Suites App SDK](https://doc.eliona.io/collection/referenzen/app-sdk) provides pre-built libraries for different programming languages to access BuildingPro Suites via the API.

### Access and Authentication

The BuildingPro Suites API can be reached via the URL path `/api/v2`. For example, if the URL for BuildingPro Suites 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 BuildingPro Suites 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.

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

### 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](https://openapi-generator.tech/docs/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.

{% 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](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 always being updated and provided via GitHub.

{% embed url="<https://github.com/eliona-smart-building-assistant/python-eliona-api-client>" %}
Python Client for BuildingPro Suites API
{% endembed %}

{% embed url="<https://github.com/eliona-smart-building-assistant/go-eliona-api-client>" %}
Go Client for BuildingPro Suites API
{% endembed %}

Postman: Importing the API Description

The OpenAPI description of the BuildingPro Suites 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>

<figure><img src="https://1888287146-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB9s2DNtIvhBdrJ64xR9g%2Fuploads%2Fy06Xa74cDM69ZY7u8yJR%2Fimage.png?alt=media&#x26;token=e486405a-9a8e-4f83-ae20-02901d94af16" alt=""><figcaption></figcaption></figure>

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 BuildingPro Suites mock is available for testing the API. This can be used independently of a complete BuildingPro Suites environment. The mock provides a complete API implementation and a simplified BuildingPro Suites database using a Docker network. The appropriate `docker-compose.yml` and the database definition are provided via GitHub:

{% embed url="<https://github.com/eliona-smart-building-assistant/eliona-mock>" %}
BuildingPro Suites-Mock
{% endembed %}