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