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
Cookies Policy
OMA NGSI 10 - FIWARE Forge Wiki

OMA NGSI 10

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the OMA NGSI 10 API

OMA 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 other GEs from the IoT Chapter of FI-WARE and the Publish/Subscribe Broker GE. 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 and binding documents for details on the resource structure and message formats.

Change history

This version of the <Name>API Guide 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

Additional Resources

This document is to be considered as a guide to the NGSI 10 API. The formal specification of NGSI 10 can be downloaded from the website of the Open Mobile Alliance.

The RESTful binding of OMA NGSI 10 described on this page has been defined by the FI-WARE project. It can be accessed in the svn. Note that also the XML schema files are part of the binding.

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

General NGSI 10 API information

Resources Summary

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 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

/contextQuery

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.

Personal tools
Create a book