5.3 NGSI-LD API
5.3.1 Overview
Figure 5.3.1-1 shows the archtectural roles in an NGSI-LD system and the interactions between them. The NGSI-LD API provides support for all these roles and interactions.
Figure 5.3.1-1: NGSI-LD Architectural Roles and Interactions
The following architectural roles exist: - The Context Broker typically has the key role in an NGSI-LD system and implements major parts of the NGSI-LD API. It can store information and transparently provides access to information stored elsewhere in case of a distributed deployment, in which case it interacts with the Context Registry. - Context Consumers typically interact only with a single Context Broker, i.e. they only need to know its URL to request or subscribe for information. - Context Producers produce information and the create, update and delete the resepective representation in the Context Broker. - Context Sources store information themselves and make it accessible through requests and subscriptions. To enable Context Brokers to find and access their information they register the information they have with the Context Registry. - The Context Registry stores the registration of the Context Sources and, when requested, provides the list of Context Sources that may have relevant information for the given request.
The NGSI-LD specification consists of two parts. An abstract API is defined in clause 5 of the specification[i.3], whereas a REST-style HTTP binding is defined in clause 6.
Figure 5.3.1-2: NGSI-LD Abstract API
All operations of the NGSI-LD Abstract API are shown in Figure 5.3.1-2, including the respective clauses in the NGSI-LD specfication[i.3], in which they are defined.
Figure 5.3.1-3: NGSI-LD Resource Structure
The NGSI-LD resource structure of the HTTP Binding of NGSI-LD as defined in clause 6 of the NGSI-LD specification[i.3] is shown in Figure 5.3.1-3.
5.3.2 Retrieve and Query operations
This section shows a number of examples for retrieving and querying Entities using the NGSI-LD API[i.3].
Retrieving an Entity
In the example the entity representing the person Sam is to be retrieved, see Figure 5.3.2-1.
Figure 5.3.2-1: NGSI-LD API - Retrieve Entity
What do applications need to know: |Element | Value | |---| --- | |Base URL | http://localhost:9090/ngsi-ld/v1/entities/ | |Entity Id | urn:ngsi-ld:Person:Sam | |Data Model | location Property | |Security credentials | [orthogonal aspect, not covered here] | |Not needed | where actual information is stored |
Retrieve request
GET /ngsi-ld/v1/entities/urn:ngsi-ld:Person:Sam?attrs=location HTTP/1.1
Host: localhost:9090
Accept: application/ld+json
Response: (NGSI-LD Entity)
{
"@context": [
{
"Person":"https://forge.etsi.org/gitlab/exampleOntology/Person",
"location":"https://forge.etsi.org/gitlab/exampleOntology/location"
},
"http://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld"
],
"id": "urn:ngsi-ld:Person:Sam",
"type": "Person",
"location": {
"type": "GeoProperty",
"value": {
"type": "Point",
"coordinates": [-8.5, 41.2]
}
}
}
Querying Entities with Geographic Scope
In the example all cars within a given geographic scope are to be queried, see Figure 5.3.2-2.
Figure 5.3.2-2: NGSI-LD API - Query Entities with Geographic Scope
What do applications need to know: |Element | Value | |---| --- | |Base URL | http://localhost:9090/ngsi-ld/v1/entities/ | |Data Model | car type | |Geographic location | coordinates | |Security credentials | [orthogonal aspect, not covered here] | |Not needed | where actual information is stored |
Query request
GET /ngsi-ld/v1/entities?type=https://forge.etsi.org/gitlab/primerContext/StoreOntology/Car&geoproperty=location&georel=near;minDistance==1500&geometry=Point& coordinates=%5B57.4874120%2C20.2845608%5D&q=speed>50
HTTP/1.1
Host: localhost:9090
Accept: application/ld+json
Excerpt of result:
[
{
"id": "urn:ngsi-ld:Car:HDB1234",
"type": “Car",
"location {
"type": "GeoProperty",
"value": {
"type": "Point",
"coordinates": [57.48765, 20.284567]
}
}
...
5.3.3 Subscription/notification operations
In the given example, the subscriber wants to be notified whenever a car is detected in the specified geographic area, see Figure 5.3.3-1.
Figure 5.3.3-1: NGSI-LD API - Subscribe to Entities with Geographic Scope
Here, two cases need to be monitored at the same time: - new car added to the system with location in the area - location of existing car has changed and is now within specified area.
What do applications need to know: |Element | Value | |---| --- | |Base URL | http://localhost:9090/ngsi-ld/v1/entities/ | |Data Model | car type, location Property | |Security credentials | [orthogonal aspect, not covered here] | |Own notification endpoint| http://localhost:9123 | |Not needed | where actual information is stored |
Subscription
POST /ngsi-ld/v1/subscriptions HTTP/1.1
Host: localhost: 9090
Content-Type: application/json
{
"id": "urn:ngsi-ld:Subscription:subscription123",
"type": "Subscription",
"entities": [
{
"type": "Car"
}
],
"geoQ": {"geoproperty":"location", "georel":"near;maxDistance==1500","geometry":"Point","coordinates":[57.48765,20.284567]},
"notification": {
"format": "normalized",
"endpoint": {
"uri": "http://localhost:9123",
"accept": "application/json"
}
}
}
{
"id": "urn:ngsi-ld:Notification:515236541235",
"type": "Notification",
"subscriptionId": "urn:ngsi-ld:Subscription:subscription123",
"data": {
"id": "urn:ngsi-ld:Car:Car12345",
"type": "Car",
"location": {
"type": "GeoProperty",
"value": {
"type": "Point",
"coordinates": [57.48765, 20.284567]
},
},
"speed": {
"type": "Property",
"value": 35
}
}
}
5.3.4 Management operations
In the example the entity representing the person Sam is to be created, see Figure 5.3.4-1.
Figure 5.3.4-1: NGSI-LD API - Create Entity
What do applications need to know: |Element | Value | |---| --- | |Base URL | http://localhost:9090/ngsi-ld/v1/entities/ | |Data Model | person type | |Entity | (Sam, see below) | |Security credentials | [orthogonal aspect, not covered here] | |Own notification endpoint| http://localhost:9123 | |Not needed | where actual information is stored |
POST /ngsi-ld/v1/entities/
HTTP/1.1
Host: localhost:9090
Content-Type: application/ld+json
{
"@context": [
{
"Person": "https://forge.etsi.org/gitlab/exampleOntology/Person",
"location":"https://forge.etsi.org/gitlab/exampleOntology/location"
},
"http://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld"
],
"id": "urn:ngsi-ld:Person:Sam",
"type": "Person",
"location {
"type": "GeoProperty",
"value": {
"type": "Point",
"coordinates": [-8.5, 41.2]
}
}
}