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
ETSI M2M mId Open RESTful API Specification (PRELIMINARY) - FIWARE Forge Wiki

ETSI M2M mId Open RESTful API Specification (PRELIMINARY)

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the ETSI M2M mId API

ETSI M2M mId API Core

The ETSI M2M mId API is a RESTful, resource-oriented API accessed via HTTP that uses XML-based or JSON-based representations for information interchange. The mId is the ETSI M2M interface between the Backend and Gateways/IoT-compliant Devices. This reference point provides the following functionality:

  • Registration of Devices/Gateways to the Backend,
  • Request to Read/Write subject to proper authorization information in the Backend,
  • Subscription and notification to specific resource-level events,
  • Device management actions (e.g. software upgrade, configuration management).

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. 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 ETSI TS 102 921: M2M; mla,dla and mld interfaces and binding documents for details on the resource structure and message formats.

API Change History

This version of the Things Management GE Northbound API Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below

Revision Date Changes Summary
June 14, 2012
  • Initial version

Additional Resources

This document is to be considered to be a guide to the planned ETSI M2M mId API elements. The complete specification can be found at ETSI TS 102 921: M2M; mla,dla and mld interfaces.

General ETSI M2M mId API Information

Image:ETSI-mId-ResourceStructure.png

Representation Format

The ETSI M2M mId API supports currently 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

In this section we list the operations that are delivered in the first release. For an in-depth specification of the listed resources and operations, please refer to the official specifications.

Data Retrieval

Container

Container resource is a generic resource that shall be used to exchange data between applications and/or SCLs by using the container as a mediator that takes care of buffering the data. Exchange of data between applications (e.g. on device and network side) is abstracted from the need to set up direct connections and allows for scenarios where both parties in the exchange are not online at the same time.

Verb URI Description
GET /{sclBase}/containers Retrieve the content of a container root resource.
PUT /{sclBase}/containers Update the content of a container root resource
GET /{sclBase}/containers/{container} Read the attributes of a container instance and references to its direct child resources.
PUT /{sclBase}/containers/{container} Update all of the attributes in a container instance.
POST /{sclBase}/containers/{container} Create a new container instance resource in a containers collection.
DELETE /{sclBase}/containers/{container} Delete the container instance.

Content Instance

A Content Instance represents a data instance in the container. The content of the instance is opaque to the M2M platform and it might even be encrypted. However, there is meta-data associated with an instance which shall be accessible.

Verb URI Description
GET /{sclBase}/containers/{container}/contentInstances Read the content of the content instances root resource. This request is used to get a list of data of all instances in the addressed contentInstances collection.
GET /{sclBase}/containers/{container}/contentInstances/{contentInstance} Read a content instance resource. This operation is used to read the entire resource or an individual attribute.
POST /{sclBase}/containers/{container}/contentInstances/{contentInstance} Adds a content instance resource to the content instances root resource.
DELETE /{sclBase}/containers/{container}/contentInstances/{contentInstance} Delete a content instance resource.

Subscription

A subscriber (an Application or an SCL) may ask to be notified when resources are modified. A subscription is the relation between the subscriber and the Hosting-SCL of the Subscribed-to Resource. The Hosting SCL shall notify the subscriber of any changes in the Subscribed-to Resource under the conditions provided when the subscription was created or modified. A subscription shall be represented by a resource itself. This allows manipulation of the subscription in a resource oriented manner, e.g. the conditions of a subscription may be modified by modifying the <subscription> resource or parts thereof, or a subscriber may unsubscribe by deleting the subscription resource. The subscriptions resource structure is present in the following places:

  • /{sclBase}/containers/subscriptions
  • /{sclBase}/containers/{container}/subscriptions
  • /{sclBase}/containers/{container}/contentInstances/subscriptions

Subscription

For keeping track of subscriptions to a subscribe-able resource, the subscriptions-resource is used as a child resource of the subscribe-able parent. The subscriptions-resource contains a collection of 0..n {subscription} resources that represent individual subscriptions to the subscribable resource (i.e. the parent of the subscriptions resource). A subscription instance resource shall represent an active (asynchronous) subscription to a resource. I.e. <resourceURI>/subscriptions/<subscription> denotes an active subscription to the resource identified by the resourceURI. Subscriptions shall only be possible on resources that have a subscriptions sub-resource.

Verb URI Description
GET {resourceURI}/subscriptions Retrieve a subscriptions root resource
GET {resourceURI}/subscriptions/{subscription} Reads a subscription instance resource
PUT {resourceURI}/subscriptions/{subscription} Updates the provided attributes of an existing subscription instance resource.
POST {resourceURI}/subscriptions/{subscription} Creates a new subscription instance resource. The subscription applies to the resource that is associated with the parent resource of the subscriptions collection resource.
DELETE {resourceURI}/subscriptions/{subscription} Deletes a subscription instance resource
Personal tools
Create a book