We use first and third-party's cookies to improve your experience and our services, identifying your Internet browsing preferences on our website. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
FI-WARE NGSI-9 Open RESTful API Specification - FIWARE Forge Wiki

FI-WARE NGSI-9 Open RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the FI-WARE NGSI-9 API

FI-WARE NGSI-9 API Core

The FI-WARE 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)

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 large number of FI-WARE Generic Enable 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 official OMA NGSI-9/NGSI-10 specification [2] and FI-WARE NGSI binding documents [5] for details on the resource structure and message formats.

Change history

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

Revision Date Changes Summary
July 14, 2012
  • 1st stable version
May 12, 2014
  • Slightly updated the descriptions to the current state of FI-WARE
May 26, 2014
  • Addressed minor peer review comments

Additional Resources

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

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

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

Legal Notice

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

General NGSI-9 API information

Resources Summary

The mapping of NGSI-9 functionality to a resource tree (see figure above) follows a twofold approach. On the one hand, there is one resource per NGSI-9 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 convenience functions 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 that are part of the binding.

Representation Format

The NGSI-9 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-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.


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

-

Attribute domain of individual context entity

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

Retrieve information on providers of information about attribute values from the domain

-

Register a provider of information about attributes from the domain

-

Context entity type

/contextEntityTypes/{tyeName}

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

-

Attribute domain of entity type

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

Retrieve information on providers of attribute values belonging to the specific domain, where the entity is of the specific type

-

Register a provider of information about attributes belonging to the specific domain, where the entity is of the specific 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
URI
HTTP verbs
POST

Notify context resource

//{notificationURI}

Generic availability notification.The expected request body is an instance of notifyContextAvailabilityRequest; the response body is an instance of notifyContextAvailabilityResponse.

[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