README.md

FIWARE Apollo

In order to allow an NGSI-LD broker to receive data sent through subscriptions by another broker, apollo translates notifications into entity creation or update requests at the NGSI-LD api. For every entity received in the data-part of a notification, the proxy first tries a POST /entities/{entityId}/attrs/ to update(and overwrite the properties) the entity. If 404 - NOT FOUND is returned by the broker, the proxy will try to create the entity via POST /entities.

This project is part of FIWARE. For more information check the FIWARE Catalogue entry for the Core Context.

Deployment

Apollo is provided as a container: https://quay.io/repository/fiware/apollo Run it via: docker run quay.io/fiware/apollo It will be available at port 8080 per default. All configurations can be provided with the standard mechanisms of the Micronaut-Framework, e.g. environment variables or appliction.yaml file. The following table concentrates on the most important configuration parameters:

Property	Env-Var	Description	Default
micronaut.server.port	MICRONAUT_SERVER_PORT	Server port to be used for the notfication proxy.	8080
micronaut.metrics.enabled	MICRONAUT_METRICS_ENABLED	Enable the metrics gathering	true
general.tenant	GENERAL_TENANT	Tenant to be used when forwarding to orion	null
micronaut.http.services.broker.url	MICRONAUT_HTTP_SERVICES_BROKER_URL	Url of the broker to forward to.	http://localhost:1027

Tenancy

The proxy does not extract any tenancy information out of the notifications. However the tenant to be used can be configured via GENERAL_TENANT=myTenant. Thus, if the setup requires multi-tenancy, runnig multiple instances of the proxy with prefiltering of the requests would be the prefered solution.

The setup can look as following: An API-Gateway handles all incoming traffic and forwards it based on the tenancy information present in the request(f.e. inside an Authorization-Header).

Development & Testing

In order to support local development and testing, a docker-compose is provided at env/docker-compose.yaml. Run it via docker-compose -f env/docker-compose.yaml up. The setup contains two Orion-LD Context Brokers, one for sending the notifications to the apollo and one for receiving the changes. Apollo itself is not included and should be started separately. The setup provides following services on localhost:

• Orion-LD for receiving data: localhost:1027 - this is the one that the proxy should be connected to
• Orion-LD for sending notifications: localhost:1026 - orion-instance to create the subscription to the proxy

Example usage:

• Run compose: docker-compose -f env/docker-compose.yaml up
• Run apollo: docker run --network host --env HTTP_SERVICES_BROKER_URL=http://localhost:1027 -p 8080:8080 quay.io/fiware/apollo
• Create a subscription:

    curl --location --request POST 'localhost:1026/ngsi-ld/v1/subscriptions/' \
        --header 'Content-Type: application/json' \
        --data-raw ' {
            "name": "mySubscription",
            "id": "urn:ngsi-ld:subscription:my-sub",
            "type": "Subscription",
            "entities": [
              {
                "type": "Cattle"
              }
            ],
            "notification": {
                "endpoint": {
                "uri": "http://localhost:8080/notification"
                }
            }
        }'

• Create an entity at the broker:

    curl --location --request POST 'localhost:1026/ngsi-ld/v1/entities' \
        --header 'Content-Type: application/json' \
        --data-raw '{
            "id": "urn:ngsi-ld:cattle:my-cattle",
            "type": "Cattle",
            "temp": {
                "type": "Property",
                "value": 37
            }
        }'

• Query receiving broker: curl --location --request GET 'localhost:1027/ngsi-ld/v1/entities/urn:ngsi-ld:cattle:my-cattle' - result:

{
    "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld",
    "id": "urn:ngsi-ld:cattle:my-cattle",
    "type": "Cattle",
    "temp": {
        "type": "Property",
        "value": 37
    }
}

• Update a property:

curl --location --request POST 'localhost:1026/ngsi-ld/v1/entities/urn:ngsi-ld:cattle:my-cattle/attrs' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "temp": {
            "type": "Property",
            "value": 40
        }
    }'

• Query receiving broker: curl --location --request GET 'localhost:1027/ngsi-ld/v1/entities/urn:ngsi-ld:cattle:my-cattle' - result:

{
    "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld",
    "id": "urn:ngsi-ld:cattle:my-cattle",
    "type": "Cattle",
    "temp": {
        "type": "Property",
        "value": 40
    }
}