Skip to main content
Version: 1.2.0

Getting started

This API provides an interface to the Stellio Context Broker, which implements the NGSI-LD standard, via the APISIX endpoint /context/ngsi-ld/.

NGSI-LD is a standard for managing context information with linked data principles, and Stellio is an open-source context broker that fully supports this standard. Stellio allows you to store, query, and manage context information such as entities, relationships, and their attributes, in compliance with the NGSI-LD data model.

In order to use an API via APISIX, you need to have an account created on our Keycloak IDM and have an administrator grant you access to a data space.

For accessing the API with valid credentials, please see How to Get an Access Token.

Data Spaces​

This API supports a generic approach to tenancy, by separating data in so-called data spaces. These spaces are reflected by tenants and can only be accessed, if your Keycloak user is in the related group and you have been granted a role to read/write/administer data in this space. To specify the tenant in a request, the header NGSILD-Tenant can be used. If no tenant is specified, the default tenant will be used.

More on the concept of tenants can be read here: Stellio Documentation

Swagger Doc​

A Swagger documentation is provided alongside this API description, detailing everything you need to work with the API.

Additional Documentation​

For more information on the Stellio API, please see the official documentation. This will cover the API in more detail and also explain how historical data can be accessed and how subscriptions can be created.

For information on NGSI-LD in general, please see the NGSI-LD Documentation. This contains tutorials and examples, which can help explain the concepts behind NGSI-LD.

Examples​

Before the following examples can be executed, an access token must be created. The following guide can help with that: How to Get an Access Token.

Tip: All cURL commands given can be used in tools like Postman by just copying the cURL command into the request field.

Create an entity​

curl --location 'https://api.civitas-core.de/context/ngsi-ld/v1/entities' \
--header 'NGSILD-Tenant: <tenant name>' \
--header 'Content-Type: application/ld+json' \
--header 'Authorization: Bearer <access token>'

alt text

Update entity to create temporal data​

curl --location 'https://api.civitas-core.de/context/ngsi-ld/v1/entityOperations/upsert?options=update' \
--header 'NGSILD-Tenant: <tenant name>' \
--header 'Content-Type: application/ld+json' \
--header 'Authorization: Bearer <access token>'

alt text

Retrieve entity context data​

curl --location 'https://api.civitas-core.de/context/ngsi-ld/v1/entities?type=TestSensorObserved' \
--header 'NGSILD-Tenant: <tenant name>' \
--header 'Fiware-ServicePath: /' \
--header 'Content-Type: application/ld+json' \
--header 'Authorization: Bearer <access token>'

alt text

Retrieve entity temporal data​

curl --location 'https://api.civitas-core.de/context/ngsi-ld/v1/temporal/entities?timerel=between&timeAt=2024-02-13T00%3A00%3A00Z&endTimeAt=2024-02-15T00%3A00%3A00Z&type=TestSensorObserved' \
--header 'NGSILD-Tenant: <tenant name>' \
--header 'Fiware-ServicePath: /' \
--header 'Content-Type: application/ld+json' \
--header 'Authorization: Bearer <access token>'

alt text