oneM2M API
The oneM2M API is used by CSEs and AEs to communicate with one another as well as for data retrieval services. oneM2M REST APIs handle CRUD+N (Create, Retrieve, Update, Delete and Notification) operations.
The oneM2M API includes the following components:
- Primitives
- Resources + Attributes
- Data Types
- Protocol Bindings
- Procedures (CRUD+N).
Primitives are used to perform CRUD+N operations on resources hosted by CSEs or to send notifications to AEs. Each CRUD+N operation consists of a pair of Request and Response primitives.
Communication can originate from an AE or a CSE depending on the operation. Communication occurs via the exchange of oneM2M primitives across three reference points (Mca/Mcc/Mcc’) defined in the oneM2M standard. Access and manipulation of the resources is subject to access control privileges.
oneM2M REST Architecture
Representational State Transfer (REST) is a software architectural style that defines a set of constraints to be used for creating web services. As REST is an architecture style, it can be mapped to multiple protocols such as HTTP, CoAP, etc.
RESTful services allow requesting systems to access and manipulate textual representations of resources by using a uniform and predefined set of stateless operations. A stateless protocol operation does not require the server to retain session information or status about each communicating partner for the duration of multiple requests.
REST is not a protocol. It is about manipulating resources, uniquely identified by URIs. A resource is stateful and may contain links pointing to another resource. All the actions on resources are done through a Uniform Interface.
Six guiding constraints define a RESTful system. These constraints restrict the ways in which a server can process and respond to client requests:
-
Client-server: separation of concerns is the principle behind the client-server constraints.
-
Stateless server: request from client to server contains all of the information necessary to understand the request, and cannot take advantage of any stored context on the server.
-
Cache: the client can reuse response data, sent by the server, by storing it in a local cache.
-
Layered system: allows an architecture to be composed of hierarchical layers. It enables the addition of features like a gateway, a load balancer, or a firewall to accommodate system scaling.
-
Code-on-demand: (optional) REST allows client functionality to be extended by downloading and executing code in the form of scripts (e.g. JavaScript).
- Uniform interface
- dentification of resources: resource identifier enables the identification of the particular resource involved in an interaction between components.
- Manipulation of resources through representations: resource representations are the state of a resource that is transferred between components.
- Self-descriptive messages: contain metadata to describe the meaning of the message.
- Hypermedia as the engine of application state (HATEOAS): Clients find their way through the API by following links available in the resource representations
oneM2M Security Mechanisms
oneM2M defines a security framework for IoT deployments consisting of the following security centric capabilities:
- enrolment
- security association establishment
- authorization
- end-to-end security
- privacy management
Enrolment: IoT applications or devices go through an initialization or joining process to connect securely to a system and become trusted. This requires provisioning and configuration of identifiers and security credentials. oneM2M supports the capability to remotely bootstrap and provision IoT devices and applications with the necessary identifiers and credentials. The oneM2M entity responsible for enrolment is called the M2M Enrolment Function (MEF).
Security association establishment: To services offered by the oneM2M Service Layer securely, devices/applications need to be mutually authenticated and establish what is known as a oneM2M security association with the Service Layer. oneM2M supports security associations based on pairwise symmetric keys, public key certificates and mutual third-party authentication. The security association results in a TLS or DTLS session being established between the oneM2M entities.
Authorization: oneM2M supports several options for authorizing the access to services and information stored within the Service Layer. The owner of the service or information can define policy rules to grant access to other oneM2M entities. Many possibilities are defined for the access rules by the Service Layer: static through an access list, dynamic with token generation, or distributed authorization system.
End-to-end security: Besides having security associations between oneM2M entities, the standard makes it possible to have end-to-end secure communication between source and destination endpoints. Hence, oneM2M supports the capability to end-to-end protect the confidentiality and integrity of oneM2M messages that flow through the Service Layer via intermediate oneM2M nodes.
Privacy management: oneM2M supports user privacy protection via a personal data management framework which converts a user’s privacy preferences into access control information that protects a user's Personally Identifiable Information. oneM2M offers users the possibility to set up their privacy preferences.
oneM2M Primitives
Primitives are service layer messages transmitted over the Mca/Mcc/Mcc’ reference points between Originators and Receivers. An Originator and Receiver can be an AE or a CSE. Each CRUD+N operation consists of one request and one response primitive.
Primitives are binded to underlying transport layer protocols such as HTTP, CoAP , MQTT or WebSocket. Primitives are generic with respect to underlying network transport protocols. The binding for each primitive can be to zero or more messages in the transport layer.
Primitive structure
A primitive consists of two parts; control and content.
-
The control part: contains parameters required for the processing of the primitive itself (e.g. request or response parameters).
-
The content part is optional based on the type of primitive and contains the representation of the resource consisting of all or a subset of the resource attributes.
Primitives are encoded and serialized based on the particular oneM2M protocol binding being used. The originator and receiver of each primitive use the same binding, and thus use compatible forms of encoding/ decoding and serialization/de-serialization. During transfer, the control part is encoded based on the protocol binding being used and the content portion is serialized using XML, JSON or CBOR.
The Content part of a primitive contains a serialized representation of a resource. Here is an example of a oneM2M <container> resource representation in JSON format.
Here is an example of a oneM2M <container> resource representation in XML format.
oneM2M Resources
This section describes the parameters that define oneM2M Resources and how they are used.
Resource Template
All information in the oneM2M System corresponding to AEs, CSEs, application data representing sensors, commands, etc. is represented as resources in the CSE. Each resource has its own specific type. Each resource type has a defined set of mandatory and optional attributes as well as child resources.
Each resource is addressable and can be the target of CRUD operations specified in oneM2M primitives.
Resource Structure
The root of the oneM2M resource structure is <CSEBase>. The <CSEBase> resource is assigned an absolute address. All other child resources are addressed relative to <CSEBase>. Depending on the type of child resource it is instantiated 0..n times.
Resource Attributes
Each resource contains attributes that store information pertaining to the resource itself.
The attributes are :
- Universal Attributes : which appear in all resources
- Common Attributes : which appear in more than one resource and have the same meaning whenever they do appear.
- Resource-specific attributes
Resource Schema
oneM2M defines XML, JSON and CBOR schemas which define the attributes of each resource type. Schemas bind oneM2M attributes to well-known data types defined by XML Schema definitions (e.g. xs:string, xs:anyURI, etc …). Schemas also bind oneM2M attributes to oneM2M defined data types (e.g. m2m:id, m2m:stringList, etc ...).
oneM2M Procedures
oneM2M defines a set of procedures for developers to access resources in local and remote CSEs. Developers can then execute CREATE, RETRIEVE, UPDATE, DELETE and NOTIFY operations.
Access Resources in Local CSE
Access Resources in Remote CSE
CREATE operation
RETRIEVE Operation
UPDATE Operation
DELETE Operation
