FI-WARE NGSI-10 Open RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the FI-WARE NGSI 10 API

Please check the following FI-WARE Open Specification Legal Notice (essential patents license) to understand the rights to use these specifications.

FI-WARE NGSI 10 API Core

The FI-WARE version of the OMA NGSI 10 interface is a RESTful API via HTTP. Its purpose is to exchange context information. The three main interaction types are

  • one-time queries for context information
  • subscriptions for context information updates (and the corresponding notifications)
  • unsolicited updates (invoked by context providers)

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:

Revision Date Changes Summary
May 14, 2012
  • 1st stable version
May 12, 2014
  • Slight changes to adopt to changes in FI-WARE.
May 26, 2014
  • Addressed minor peer review comments

Additional Resources

The formal specification of OMA NGSI 10 can be downloaded from the website of theOpen Mobile Alliance.

The FI-WARE RESTful binding of OMA NGSI-10 described on this page has been defined by the FI-WARE project. It can be accessed from the list of publicly available documents.

FI-WARE NGSI-10 and FI-WARE NGSI-9 share the same NGSI-9/10 information model. Be sure to have read it before continuing on this page.

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.

Resource
Base URI: http://{serverRoot}/NGSI10
HTTP verbs
POST

Context query resource

/queryContext

Generic queries for context information.The expected request body is an instance of queryContextRequest; the response body is an instance of queryContextResponse.

Subscribe context resource

/subscribeContext

Generic subscriptions for context information. The expected request body is an instance of subscribeContextRequest; the response body is an instance of subscribeContextResponse.

Update context subscription resource

/updateContextSubscription

Generic update of context subscriptions. The expected request body is an instance of updateContexSubscriptiontRequest; the response body is an instance of updateContextSubscriptionResponse.

Unsubscribe context resource

/unsubscribeContext

Generic unsubscribe operations. The expected request body is an instance of unsubscribeContextRequest; the response body is an instance of unsubscribeContextResponse.

Update context resource

/updateContext

Generic context updates. The expected request body is an instance of updateContextRequest; the response body is an instance of updateContextResponse.


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}/NGSI10
HTTP verbs
GET
PUT
POST
DELETE

Individual context entity

/contextEntities/{EntityID}

Retrieve all available information about the context entity

Replace a number of attribute values

Append context attribute values

Delete all entity

information

Attribute container of individual context entity

/contextEntities/{EntityID}/attributes

Retrieve all available information about context entity

Replace a number of attribute values

Append context attribute values

Delete all entity

information

Attribute of individual context entity

/contextEntities/{EntityID}/attributes/{attributeName}

Retrieve attribute value(s) and associated metadata

-

Append context attribute value

Delete all attribute values

Specific attribute value of individual context entity

/contextEntities/{EntityID}/attributes/{attributeName}/{attributeID}

Retrieve specific attribute value

Replace attribute value

-

Delete attribute value

Attribute domain of individual context entity

/contextEntities/{EntityID}/attributeDomains/{attributeDomainName}

Retrieve all attribute information belonging to attribute domain

-

-

-

Context entity type

/contextEntityTypes/{tyeName}

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.

References

[1]

https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/NGSI_9/10_information_model

[2]

http://technical.openmobilealliance.org/Technical/release_program/docs/NGSI/V1_0-20120529-A/OMA-TS-NGSI_Context_Management-V1_0-20120529-A.pdf

[3]

https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_NGSI-9_Open_RESTful_API_Specification_%28PRELIMINARY%29

[4]

https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_NGSI-10_Open_RESTful_API_Specification_%28PRELIMINARY%29

[5]

https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_NGSI_Open_RESTful_API_Specification

[6]

https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/NGSI_association

[7]

https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_Architecture

[8]

https://forge.fi-ware.eu/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_Open_Specifications_Legal_Notice

[9]

http://edu.fi-ware.eu/course/view.php?id=33

Personal tools
Create a book