We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy

Intended Audience

This guide is intended for both developers of GE implementations and IoT Application programmers. For the former, this document specifies the API that has to be implemented in order to ensure interoperability with the numerous FI-WARE Generic Enablers that expose NGSI interfaces. For the latter, this document describes how to assemble instances of the FI-WARE IoT Platform.

Prerequisites: Throughout this specification it is assumed that the reader is familiar with

ReSTful web services

HTTP/1.1

XML data serialization formats

We also refer the reader to the NGSI-9/10 specification [2] and binding documents [5] for details on the resource structure and message formats.

Change history

This version of the FI-WARE NGSI-10 Open RESTful API Specification replaces and obsoletes all previous versions. The most recent changes are described in the table below:

General NGSI 10 API information

Resources Summary

The following scheme shows the resources tree in NGSI-9/10 schema of REST resources.

Schema of REST resources in NGSI-9/10

The mapping of NGSI-10 functionality to a resource tree (see figure above) follows a twofold approach. On the one hand, there is one resource per NGSI-10 operation which supports the respective functionality by providing a POST operation (colored green in the picture). On the other hand, a number of additional resources support convenience functionality (colored yellow). The latter resource structure more closely follows the REST approach and typically supports more HTTP operations (GET PUT, POST, and DELETE). The operation scope of the GET operation on these resources can further be limited by a URI parameter.

The convenience functions typically only support a subset of the functionality of the corresponding NGSI operations. Nevertheless, they enable simpler and more straightforward access.
All data structures, as well as the input and output messages are represented by xml types. The definition of these types can be found in the xml schema files, and some examples are shown below.

Representation Format

The NGSI 10 API supports only XML as data serialization format.

Representation Transport

Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.

API Operations on Context Management Component

Standard NGSI-10 Operation Resources

The five resources listed in the table below represent the five operations offered by systems that implement the NGSI-10 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.

Retrieve all available information about all context entities having that entity type

-

-

-

Attribute container of entity type

/contextEntityTypes/{typeName}/attributes

Retrieve all available information about all context entities having that entity type

-

-

-

Attribute of entity type

/contextEntityTypes/{typeName}/attributes/{attributeName}

Retrieve all attribute values of the context entities of the specific entity type

-

-

-

Attribute domain of entity type

/contextEntityTypes/{typeName}/attributeDomains/{attributeDomainName}

For all context entities of the specific type, retrieve the values of all attributes belonging to the attribute domain.

-

-

-

Subscriptions container

/contextSubscriptions

-

-

Create a new subscription

-

Subscription

/contextSubscriptions/{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 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

URI

HTTP verbs

POST

Notify context resource

//{notificationURI}

Generic notification.The expected request body is an instance of notifyContextRequest; the response body is an instance of notifyContextResponse.