FIWARE Lepus

An NGSI-LD wrapper for use with NGSI-v2 Context Brokers. It understands the NGSI-LD endpoints and inputs, converts them to NGSI-v2, makes a request to the NGSI-v2 broker behind it and transforms responses back to NGSI-LD using a fixed JSON-LD @context. It supports the NGSI-LD federationOps endpoints only and is designed to be used as a registered source with NGSI-LD Context Brokers in federation mode.

Example

Give me the Stores with the name "Einkauf" in NGSI-LD format

curl -L 'https://<lepus-context-broker>/ngsi-ld/v1/entities?type=Store&q=name%22Einkauf%22' \
-H 'Link: <http://context/ngsi-context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \
-H 'Accept: application/ld+json'

is transformed to Give me the Stores with the name "Einkauf" in NGSI-v2 format

curl -L 'https://<ngsi-v2-context-broker>/v2/entities?type=Store&q=nameEinkauf' \
-H 'Accept: application/json'

All NGSI-v2 response attributes are converted to Property or Relationship (or subtype) and a fixed @context added to the body or Link header.

Supported Endpoints

The following endpoints are supported as defined in the latest NGSI-LD Specification

Entities

GET /entities/ - Query entities - §5.7.2; §6.4.3.2
POST /entities/ - Entity creation - §5.6.1; §6.4.3.1
DELETE /entities/ - Purge Entities

GET /entities/{entityId} - Entity retrieval by ID - §5.7.1; §6.5.3.1
PATCH /entities/{entityId} - Merge Entity - §5.6.17; §6.5.3.4
PUT /entities/{entityId} - Replace Entity - §5.6.17; §6.5.3.3
DELETE /entities/{entityId} - Entity retrieval by ID - §5.6.6; §6.5.3.2

POST /entities/{entityId}/attrs - Append Entity attributes - §5.6.3; §6.6.3.1
PATCH /entities/{entityId}/attrs - Update Entity attributes - §5.6.2; §6.6.3.2

DELETE /entities/{entityId}/{attr} - Delete Entity attribute - §5.6.5; §6.7.3.2
PUT /entities/{entityId}/{attr} - Replace Entity attribute - §5.6.19; §6.7.3.3

Subscriptions

POST /subscriptions/ - Create Subscription - §5.8.1; §6.10.3.1
GET /subscriptions/ - Retrieve list of Subscriptions - §5.8.4; §6.10.3.2
GET /subscriptions/{subscriptionId} - Subscription retrieval by ID - §5.8.3; §6.11.3.1
PATCH /subscriptions/{subscriptionId} - Subscription update by ID - §5.8.2; §6.11.3.2
DELETE /subscriptions/{subscriptionId} - Subscription deletion by ID - §5.8.5; §6.11.3.3

Types

GET /types/ - Retrieve available entity types - §5.7.5; §5.7.6; §6.25.3.1
GET /types/{type} - Details about available entity type - §5.7.7; §6.26.3.1

Attributes

GET /attributes/ - Available attributes - §5.7.8; §5.7.9; §6.27.3.1
GET /attributes/{attrId} - Details about available attribute - §5.7.10; §6.28.3.1

Batch Operations

POST /entityOperations/create - Batch Entity creation - §5.6.7; 6.14.3.1
POST /entityOperations/upsert - Batch Entity create or update (upsert) - §5.6.8; §6.15.3.1
POST /entityOperations/update - Batch Entity update - §5.6.9; §6.16.3.1
POST /entityOperations/delete - Batch Entity deletion - §5.6.10; §6.17.3.1

POST /entityOperations/query - Query entities based on POST - §5.7.2; §6.23.3.1 ❌

POST /entityOperations/merge - Batch Entity merge - §5.6.20; §6.31.3.1 ❌

Internally

POST /notify/ receives NGSI-v2 notifications and forwards then as NGSI-LD

Usage

To use the wrapper, run:

 docker-compose up

Then insert some data into an NGSI-v2 broker such as Telefónica's Orion Context Broker

curl -L 'http://localhost:1026/v2/entities/' \
-H 'Content-Type: application/json' \
-d '{
    "id": "urn:ngsi-ld:Store:001",
    "type": "Store",
    "address": {
        "type": "PostalAddress",
        "value": {
            "streetAddress": "Bornholmer Straße 65",
            "addressRegion": "Berlin",
            "addressLocality": "Prenzlauer Berg",
            "postalCode": "10439"
        },
        "metadata": {
    		"verified": {
        		"value": true,
        		"type": "Boolean"
    		}
    	}
    },
    "location": {
        "type": "geo:json",
        "value": {
             "type": "Point",
             "coordinates": [13.3986, 52.5547]
        }
    },
    "name": {
        "type": "Text",
        "value": "Bösebrücke Einkauf"
    }
}'

curl -L 'http://localhost:1026/v2/entities/' \
-H 'Content-Type: application/json' \
-d '{
  "type": "Store",
    "id": "urn:ngsi-ld:Store:002",
    "address": {
        "type": "PostalAddress",
        "value": {
            "streetAddress": "Friedrichstraße 44",
            "addressRegion": "Berlin",
            "addressLocality": "Kreuzberg",
            "postalCode": "10969"
        },
        "metadata": {
    		"verified": {
        		"value": true,
        		"type": "Boolean"
    		}
    	}
    },
    "location": {
        "type": "geo:json",
        "value": {
             "type": "Point",
             "coordinates": [13.3903, 52.5075]
        }
    },
    "name": {
        "type": "Text",
        "value": "Checkpoint Markt"
    }
}'

Now query Lepus Accept: application/ld+json as if it is an NGSI-LD source - e.g.

curl -L 'http://<lepus-context-broker>/ngsi-ld/v1/types' \
-H 'Link: <http://context/ngsi-context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \
-H 'Accept: application/ld+json'

returns NGSI-LD with a fixed @context

{
    "id": "urn:ngsi-ld:EntityTypeList:a1993de4-83e0-44c9-990b-be2e84b31df1",
    "type": "EntityTypeList",
    "typeList": [
        "Store"
    ],
    "@context": [
        "https://fiware.github.io/tutorials.Step-by-Step/tutorials-context.jsonld",
        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"
    ]
}

Alternatively query Lepus with Accept: application/json

curl -iX 'https://<lepus-context-broker>/ngsi-ld/v1/types' \
-H 'Link: <https://<lepus-context-broker>/context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \
-H 'Accept: application/json'

Returns

Link: <https://<lepus-context-broker>/context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

{
    "id": "urn:ngsi-ld:EntityTypeList:a1993de4-83e0-44c9-990b-be2e84b31df1",
    "type": "EntityTypeList",
    "typeList": [
        "Store"
    ]
}

And https://<lepus-context-broker>/context.jsonld returns NGSI-LD with a fixed @context

{
    "@context": [
        "https://fiware.github.io/tutorials.Step-by-Step/tutorials-context.jsonld",
        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld"
    ]
}

Configuration

Configuration occurs using Docker Environment variables:

DEBUG - for debug output - e.g. DEBUG=adapter:*
LEPUS_PORT - port used for interactions - defaults to 3000
LEPUS_ALIAS - host alias for Lepus
LEPUS_RELAY_TIMEOUT maximum length of time to forward the NGSI-LD notification
LEPUS_URL for the location of Lepus itself - e.g. LEPUS_URL=http://<lepus>
LEPUS_MULTI_CORE - whether to use multiple cores
INCLUDE_VALUE_TYPE - include the NGSI-v2 attribute type in the returned payload
NGSI_V2_CONTEXT_BROKER for the NGSI-v2 Orion Context Broker URL - e.g. NGSI_V2_CONTEXT_BROKER=http://orion2:1026
NGSI_V2_TIMEOUT maximum length of time to access the NGSI-v2 Orion Context Broker URL in milliseconds
USER_CONTEXT_URL for the fixed JSON-LD @context to be supplied - e.g. USER_CONTEXT_URL=https://fiware.github.io/tutorials.Step-by-Step/tutorials-context.jsonld
CORE_CONTEXT_URL for the fixed core NGSI-LD @context to be supplied - e.g. CORE_CONTEXT_URL=https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.8.jsonld

NGSI-LD Registration

Since Lepus does not understand JSON-LD directly, registrations must be created within an LD context broker using the "key": "jsonldContext" to preprocess all interactions:

curl -L 'http://localhost:9090/ngsi-ld/v1/csourceRegistrations/' \
-H 'Content-Type: application/json' \
-H 'Link: <https://<lepus-context-broker>/context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \
-d ' {
    "type": "ContextSourceRegistration",
    "information": [
        {
            "entities": [
                {
                    "type": "Shelf"
                }
            ]
        }
    ],
     "contextSourceInfo":[
        {
            "key": "jsonldContext",
            "value": "https://<lepus-context-broker>/context.jsonld"
        }
    ],
    "mode": "inclusive",
    "operations": [
        "federationOps"
    ],
    "endpoint": "https://<lepus-context-broker>"
}'

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
.github		.github
bin		bin
controllers		controllers
lib		lib
routes		routes
test		test
.env		.env
.eslintignore		.eslintignore
.eslintrc		.eslintrc
.gitignore		.gitignore
.prettierrc.json		.prettierrc.json
.textlintrc		.textlintrc
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
app.js		app.js
config.js		config.js
docker-compose.yml		docker-compose.yml
package.json		package.json

License

jason-fox/lepus

Folders and files

Latest commit

History

Repository files navigation

FIWARE Lepus

Example

Supported Endpoints

Entities

Subscriptions

Types

Attributes

Batch Operations

Usage

Configuration

NGSI-LD Registration

License

About

Topics

Resources

License

Stars

Watchers

Forks

Languages