apiary.apib

FORMAT: 1A
HOST: https://app.apiary.io/ngsi9
TITLE: IoT Discovery GE Open API Specification
DATE: 17/09/2016
VERSION: Release_5
APIARY_PROJECT: ngsi9
SPEC_URL: http://
GITHUB_SOURCE: https://github.com/UniSurreyIoT/fiware-iot-discovery-ngsi9/blob/master/doc/apiary/ngsi9-server.apib

# FIWARE NGSI-9 API Core (v1)

The FIWARE version of the OMA NGSI-9 interface is a RESTful API via HTTP. Its purpose is to exchange information about the availability of context information. The three main interaction types are
* one-time queries for discovering hosts (also called 'agents' here) where certain context information is available
* subscriptions for context availability information updates (and the corresponding notifications)
* registration of context information, i.e. announcements that certain context information is available (invoked by context providers)

## Editors

  + Tarek Elsaleh (UNIS)

## Copyright

Copyright (c) 2016 UNIS

## License

This specification is licensed under the
[FIWARE Open Specification License (implicit patent license)](https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/Implicit_Patents_License).
  
## Acknowledgements

Main contributers to the FIWARE NGSI-9 Binding Specification: 

Fermin Galan Marquez (TID), Tobias Jacobs (NEC), Ken Gunner (TID), Salvatore Longo (NEC), Martin Bauer (NEC), Juanjo Hierro (TID), Boris Moltchanov (TI), Laurent Artusio (FT)

## Versions

+ This Version: http://docs.ngsi9.apiary.io/

## Status

FIWARE Release 5

## Conformance

All the interfaces described by this specification are mandatory and must be implemented in order to be compliant with. 

# Specification

This section is intended to describe the main concepts, constructs, data structures etc. used by your specification.

## Introduction

###Standard NGSI-9 Operation Resources
The five resources listed in the table below represent the five operations offered by systems that implement the NGSI-9 Context Management role. Each of these resources allows interaction via http POST. All attempts to interact by other verbs shall result in an HTTP error status 405; the server should then also include the ‘Allow: POST’ field in the response.

| Resource | Base URI: http://{serverRoot}/ngsi9 | HTTP verbs |
|----|----|----|
|   |  | POST|
|Context Registration Resource |/registerContext|Generic context registration. The expected request body is an instance of registerContextRequest; the response body is an instance of registerContextResponse.|
|Discovery resource|/discoverContextAvailability|Generic discovery of context information providers. The expected request body is an instance of discoverContextAvailabilityRequest; the response body is an instance of discoverContextAvailabilityResponse.|
|Availability subscription resource|/subscribeContextAvailability|Generic subscription to context availability information. The expected request body is an instance of subscribeContextAvailabilityRequest; the response body is an instance of subscribeContextAvailabilityResponse.|
|Availability subscription update resource|/updateContextAvailabilitySubscription|Generic update of context availability subscriptions. The expected request body is an instance of updateContextAvailabilitySubscriptionRequest; the response body is an instance of updateContextAvailabilitySubscriptionResponse.|
|Availability subscription deletion resource|/unsubscribeContextAvailability|Generic deletion of context availability subscriptions. The expected request body is an instance of unsubscribeContextAvailabilityRequest; the response body is an instance of unsubscribeContextAvailabilityResponse.|
|Notify context resource|/{notificationURI}|Generic availability notification.The expected request body is an instance of notifyContextAvailabilityRequest; the response body is an instance of notifyContextAvailabilityResponse.|

###Convenience Operation Resources
The table below gives an overview of the resources for convenience operation and the effects of interacting with them via the standard HTTP verbs GET, PUT, POST, and DELETE.

|Resource|Base URI: http://{serverRoot}/ngsi9|HTTP verbs||||
|----|----|----|----|----|----|----|
|   |  | GET|PUT|POST|DELETE|
|Individual context entity |/contextEntities/{EntityID}|Retrieve information on providers of any information about the context entity|-|Register a provider of information about the entity|-|
|Attribute container of individual context entity|/contextEntities/{EntityID}/attributes|Retrieve information on providers of any information about the context entity|-|Register a provider of information about the entity|-|
|Attribute of individual context entity|/contextEntities/{EntityID}/attributes/{attributeName}|Retrieve information on providers of the attribute value|-|Register a provider of information about the attribute|-|
|Context entity type|/contextEntityTypes/{typeName}|Retrieve information on providers of any information about context entities of the type|-|Register a provider of information about context entitie of the type|-|
|Attribute container of entity type|/contextEntityTypes/{typeName}/attributes|Retrieve information on providers of any information about context entities of the type|-|Register a provider of information about context entitie of the type|-|
|Attribute of entity type|/contextEntityTypes/{typeName}/attributes/{attributeName}|Retrieve information on providers of values of this attribute of context entities of the type|-|Register a provider of information about this attribute of context entities of the type|-|
|Availability subscription container|/contextAvailabilitySubscriptions|-|-|Create a new availability subscription|-|
|Availability subscription|/contextAvailabilitySubscriptions/{subscriptionID}|-|Update subscription|-|Cancel subscription

###API operation on Context Consumer Component
This section describes the resource that has to be provided by the context consumer in order to receive availability notifications. All attempts to interact with it by other verbs than POST shall result in an HTTP error status 405; the server should then also include the ‘Allow: POST’ field in the response.

|Resource|Base URI: http://{serverRoot}/ngsi9|HTTP verbs|
|----|----|----|
|   |  | POST|
|Notify context resource|//{callbackURL}|Generic availability notification.The expected request body is an instance of notifyContextAvailabilityRequest; the response body is an instance of notifyContextAvailabilityResponse.|

## Terminology

## Concepts

###Basic NGSI Context Management Information Model

####Entities
The central aspect of the NGSI-9/10 information model is the concept of entities. Entities are the virtual representation of all kinds of physical objects in the real world. Examples for physical entities are tables, rooms, or persons. Virtual entities have an identifier and a type. For example, a virtual entity representing a person named “John” could have the identifier “John” and the type “person”.

####Attributes
Any available information about physical entities is expressed in the form of attributes of virtual entities. Attributes have a name and a type as well. For example, the body temperature of John would be represented as an attribute having the name “body_temperature” and the type “temperature”. Values of such attributes are contained by value containers. This kind of container does not only consist of the actual attribute value, but also contains a set of metadata. Metadata is data about data; in in our body temperature example this metadata could represent the time of measurement, the measurement unit, and other information about the attribute value.

####Attribute Domains
There also is a concept of attribute domains in OMA NGSI 9/10. An attribute domain logically groups together a set of attributes. For example, the attribute domain "health_status" could comprise of the attributes "body_temperature" and "blood_pressure".

####Context Elements
The data structure used for exchanging information about entities is context element. A context element contains information about multiple attributes of one entity. The domain of these attributes can also be specified inside the context element; in this case all provided attribute values have to belong to that domain.
Formally, a context element contains the following information
an entity id and type
a list of triplets <attribute name, attribute type, attribute value> holding information about attributes of the entity
(optionally) the name of an attribute domain
(optionally) a list of triplets <metadata name, metadata type, metadata value> that apply to all attribute values of the given domain
NGSI Context Management Interfaces

OMA NGSI defines two interfaces for exchanging information based on the information model. The interface OMA NGSI-10 is used for exchanging information about entities and their attribute, i.e., attribute values and metadata. The interface OMA NGSI-9 is used for availability information about entities and their attributes. Here, instead of exchanging attribute values, information about which provider can provide certain attribute values is exchanged.

## Data Structures


# REST API

# Group Root

### Context Registration Resource [POST /registerContext]

You may create your own request using this action. It takes a JSON
object containing a RegisterContextRequest message.

+ Request (application/json)

        {
        "contextRegistrations": [
            {
            "entities": [
                {
                    "type": "Room",
                    "isPattern": "false",
                    "id": "Room1"
                },
            {
                "type": "Room",
                "isPattern": "false",
                "id": "Room2"
            }
                        ],
            "attributes": [
                {
                    "name": "temperature",
                    "type": "float",
                    "isDomain": "false"
          },
            {
            "name": "pressure",
            "type": "integer",
            "isDomain": "false"
            }
                            ],
            "providingApplication": "http://mysensors.com/Rooms"
            }
            ],
            "duration": "P1M"
        }

+ Response 201 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "duration" : "P1M",
            "registrationId" : "52a744b011f5816465943d58"
            }

### Discover Context availability operation [POST /discoverContextAvailability]

You may create your own request using this action. It takes a JSON
object containing a discoverContextAvailabilityRequest message.

+ Request (application/json)

        {
        "entities": [
            {
            "type": "Room",
            "isPattern": "false",
            "id": "Room1"
            }
        ],
        "attributes": [
            "temperature"
        ]
        }

+ Response 200 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "contextRegistrationResponses": [
            {
            "contextRegistration": {
            "attributes": [
            {
              "isDomain": "false",
              "name": "temperature",
              "type": "float"
            }
            ],
            "entities": [
            {
              "id": "Room1",
              "isPattern": "false",
              "type": "Room"
            }
            ],
            "providingApplication": "http://mysensors.com/Rooms"
            }
            }
            ]
            }

### Subscribe to Context availability operation [POST /subscribeContextAvailability]

You may create your own request using this action. It takes a JSON
object containing a subscribeContextAvailability message.

+ Request (application/json)

        {
        "entities": [
        {
         "type": "Room",
         "isPattern": "true",
         "id": ".*"
        }
        ],
        "attributes": [
        "temperature"
        ],
        "reference": "http://localhost:8080/accumulate",
        "duration": "P1M"
        }

+ Response 201 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "duration": "P1M",
            "subscriptionId": "52a745e011f5816465943d59"
            }
  
### Update Subscription to Context availability operation [POST /updateContextAvailabilitySubscription]

You may create your own request using this action. It takes a JSON
object containing a updateContextAvailabilitySubscriptionRequest message.

+ Request (application/json)

        {
        "entities": [
        {
         "type": "Room",
         "isPattern": "true",
         "id": ".*"
        }
        ],
        "attributes": [
        "temperature"
        ],
        "reference": "http://localhost:8080/accumulate",
        "duration": "P1M"
        }

+ Response 201 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "duration": "P1M",
            "subscriptionId": "52a745e011f5816465943d59"
            }

### Unsubscribe to Context availability operation [POST /unsubscribeContextAvailability]

You may create your own request using this action. It takes a JSON
object containing a unsubscribeContextAvailabilityRequest message.

+ Request (application/json)

        {
        "subscriptionId": "52a745e011f5816465943d59"
        }

+ Response 201 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "statusCode": {
            "code": "200",
            "reasonPhrase": "OK"
            },
            "subscriptionId": "52a745e011f5816465943d59"
            }  
  
### Notify Context availability operation [POST /{callbackURL}]

This operation is initiated by the NGSI-9 server, when a registration match a subscription. It sends a JSON
object containing a NotifyContextAvailabilityRequest message, and receives from the subscriber a NotifyContextAvailabilityResponse message

+ Request (application/json)

        {
        "subscriptionId": "52a745e011f5816465943d59",
        "contextRegistrationResponses": [
        {
            "contextRegistration": {
                "entities": [
                    {
                        "type": "Room",
                        "isPattern": "false",
                        "id": "Room1"
                    },
                    {
                        "type": "Room",
                        "isPattern": "false",
                        "id": "Room2"
                    }
                ],
                "attributes": [
                    {
                        "name": "temperature",
                        "type": "float",
                        "isDomain": "false",
                        "metadatas": [
                            {
                                "name": "accuracy",
                                "type": "float",
                                "value": "0.8"
                            }
                        ]
                    }
                ],
                "providingApplication": "http://mysensors.com/Rooms"
            }
        }
        ]
        }

+ Response 201 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "statusCode": {
            "code": "200",
            "reasonPhrase": "OK"
            }
            }
            
# Convenience operations [/]

Instances of this resource type are used for retrieving which information about a certain context entity is available. Furthermore, the availability of context information about this entity can be announced by interaction with this resource.

The {entitityID} part of the resource URI must denote the ID of an individual entity. The usage of regular expressions in {entityID} is supported neither here nor for any subresource.

## Convenience operation - Individual Context Entity    [/contextEntities/{EntityID}]

### Register Context  [POST]

This operation registers the availability of context information about the entity identified by the {entityID} part of the resource URI. Note that this operation can be used both for new registrations and for updates of existing registrations; in the latter case the request message should include the RegistrationId field.

The request message is an instance of registerProviderRequest. The response message is an instance of registerContextResponse.

+ Request (application/json)

        {
        "contextRegistrations": [
            {
            "entities": [
                {
                    "type": "Room",
                    "isPattern": "false",
                    "id": "Room1"
                },
            {
                "type": "Room",
                "isPattern": "false",
                "id": "Room2"
            }
                        ],
            "attributes": [
                {
                    "name": "temperature",
                    "type": "float",
                    "isDomain": "false"
          },
            {
            "name": "pressure",
            "type": "integer",
            "isDomain": "false"
            }
                            ],
            "providingApplication": "http://mysensors.com/Rooms"
            }
            ],
            "duration": "P1M"
        }

+ Response 201 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "duration" : "P1M",
            "registrationId" : "52a744b011f5816465943d58"
            }


### Discover Context [GET]

Retrieve all availability information about the context entity represented by the resource (i.e. URIs of all applications that provide context information about the entity).
The response body is an instance of DiscoverContextAvailabilityResponse. Its ContextRegistrationResponseList contains context availability information related to the context entity that is determined by the {entitityID} part of the resource URI.

Use a GET request to retreive results for the {EntityID} specified in the URL path.

+ Response 200 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "contextRegistrationResponses": [
            {
            "contextRegistration": {
            "attributes": [
            {
              "isDomain": "false",
              "name": "temperature",
              "type": "float"
            }
            ],
            "entities": [
            {
              "id": "Room1",
              "isPattern": "false",
              "type": "Room"
            }
            ],
            "providingApplication": "http://mysensors.com/Rooms"
            }
            }
            ]
            }

## Convenience operation - Attribute of Individual Context Entity    [/contextEntities/{EntityID}/attributes/{attributeName}]

### Discover Context [GET]

Retrieve all availability information about the attribute represented by the resource, including the respective metadata. The response body is an instance of DiscoverContextAvailabilityResponse, where the same restrictions as for GET operations on context entity resources apply. Additionally, only availability information related to the attribute determined by the {attributeName} part of the resource URI must be contained in the response.

Use a GET request to retreive results for the {EntityID} and {attributeName} specified in the URL path.

+ Response 200 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "contextRegistrationResponses": [
            {
            "contextRegistration": {
            "attributes": [
            {
              "isDomain": "false",
              "name": "temperature",
              "type": "float"
            }
            ],
            "entities": [
            {
              "id": "Room1",
              "isPattern": "false",
              "type": "Room"
            }
            ],
            "providingApplication": "http://mysensors.com/Rooms"
            }
            }
            ]
            }
            
## Convenience operation - Context Entity Type    [/contextEntities/ContextEntityType/{typeName}]

Instances of this resource are used for retrieving availability information about context entities of the type represented by the resourceand announce the availability of such information.

### Discover Context [GET]

Retrieve availability of information about context entities of the type represented by this resource. The response body is an instance of discoverContextAvailabilityResponse, which only contains availability information related to entities having type {typeName}.
Use a GET request to retreive results for the {typeName} specified in the URL path.

+ Response 200 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "contextRegistrationResponses": [
            {
            "contextRegistration": {
            "attributes": [
            {
              "isDomain": "false",
              "name": "temperature",
              "type": "float"
            }
            ],
            "entities": [
            {
              "id": "Room1",
              "isPattern": "false",
              "type": "Room"
            }
            ],
            "providingApplication": "http://mysensors.com/Rooms"
            }
            }
            ]
            }

## Convenience operation - Attribute of Context Entity Type    [/contextEntityTypes/{typeName}/attributes/{attributeName}]

Instances of this resource are used for retrieving availability information regarding a specific attribute of all context entities having a certain type, and for announcing the availability of such kind of information.

### Discover Context [GET]

Retrieve information on where values of the the attribute represented by the resource is available, and what the respective metadata is. The context entities of interest are all context entities of the type represented by the {typeName} part of the access URI.

+ Response 200 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "contextRegistrationResponses": [
            {
            "contextRegistration": {
            "attributes": [
            {
              "isDomain": "false",
              "name": "temperature",
              "type": "float"
            }
            ],
            "entities": [
            {
              "id": "Room1",
              "isPattern": "false",
              "type": "Room"
            }
            ],
            "providingApplication": "http://mysensors.com/Rooms"
            }
            }
            ]
            }

## Convenience operation - Availability Subscription [/contextAvailabilitySubscriptions]

This is a container resource for context availability subscriptions, where new subscriptions are created via POST.

### Create a new availability subscription [POST]

Create a new context availability subscription. The type of the request and response body is SubscribeContextAvailabilityRequest and SubscribeContextAvailabilityResponse, respectively. The subscription will be represented by a new child resource, whose URI is determined by the subscription ID inside the response body. The recipient URI of the subscription is to be specified in the Reference field of the the request body.

You may create your own request using this action. It takes a JSON object containing a subscribeContextAvailability message.

+ Request (application/json)

        {
        "entities": [
        {
         "type": "Room",
         "isPattern": "true",
         "id": ".*"
        }
        ],
        "attributes": [
        "temperature"
        ],
        "reference": "http://localhost:8080/accumulate",
        "duration": "P1M"
        }

+ Response 201 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "duration": "P1M",
            "subscriptionId": "52a745e011f5816465943d59"
            }

## Convenience operation - Availability Subscription Container [/contextAvailabilitySubscriptions/{subscriptionID}]

Instances of this resource represent context availability subscriptions. They can be interacted with via PUT and DELETE. Creation of new availability subscriptions is done by interaction with the parent resource.

### Update Subscription [PUT]

This operation updates a context availability subscription. The request and response body is updateContextAvailabilitySubscriptionRequest and updateContextAvailabilitySubscriptionResponse, respectively. The subscriptionId field inside the request message must equal the {subscriptionID} part of the access URI, otherwise an error shall be returned.

You may create your own request using this action. It takes a JSON object containing a updateContextAvailabilitySubscriptionRequest message.

+ Request (application/json)

        {
        "entities": [
        {
         "type": "Room",
         "isPattern": "true",
         "id": ".*"
        }
        ],
        "attributes": [
        "temperature"
        ],
        "reference": "http://localhost:8080/accumulate",
        "duration": "P1M"
        }

+ Response 201 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "duration": "P1M",
            "subscriptionId": "52a745e011f5816465943d59"
            }

### Cancel Subscription [DELETE]

This operation is used for deleting a context availability subscription, which corresponds to an unsubscribeContextAvailability operation. The request contains no body, and the response body is of type UnsubscribeContextAvailabilityResponse.

You may create your own request using this action. It takes a JSON object containing a updateContextAvailabilitySubscriptionRequest message.

+ Request (application/json)

        {
        "entities": [
        {
         "type": "Room",
         "isPattern": "true",
         "id": ".*"
        }
        ],
        "attributes": [
        "temperature"
        ],
        "reference": "http://localhost:8080/accumulate",
        "duration": "P1M"
        }

+ Response 201 (application/json)

    + Headers

            Location: /ngsi9

    + Body

            {
            "duration": "P1M",
            "subscriptionId": "52a745e011f5816465943d59"
            }