What are oneM2M Requests?
This article provides an overview of the oneM2M requests and how they are used to interact with a oneM2M system.
oneM2M Request and Response Procedures
oneM2M follows a RESTful approach for its request and response procedures. This means that for every request that is sent from an originator to a receiver, the receiver must send a response back to the originator with the result of the request processing. The response is sent back to the originator using the same protocol that was used for the request.
Sending of requests and receiving of responses via the Mca or Mcc reference points is done by protocol bindings that implement the technical transport protocols between originators and receivers. This could be, for example, HTTP, CoAP, MQTT, or WebSockets.
The following figure shows the basic request and response procedures in oneM2M.
sequenceDiagram
Originator ->> Receiver: Request
activate Receiver
Receiver -->> Receiver: Handle Request
Receiver ->> Originator: Response
deactivate Receiver
oneM2M Operations
oneM2M defines a set of operations that are used to interact with the oneM2M system. These operations are defined as RESTful operations and are used to create, retrieve, update, and delete resources as well as to send notifications in a oneM2M system. The following table lists these operations and their meaning.
| Operation | Meaning |
|---|---|
| CREATE | Create a new resource in a oneM2M resource tree. This operation is also used to register Application Entities. |
| RETRIEVE | Retrieve a resource from a oneM2M resource tree. A special case of a RETRIEVE operation is the DISCOVERY operation that is used to search for resources in a oneM2M resource tree. |
| UPDATE | Update a resource in a oneM2M resource tree. |
| DELETE | Delete a resource from the oneM2M system. |
| NOTIFY | Send a notification to an entity in the oneM2M system. |
Table 1: oneM2M Operations
oneM2M Request and Response Structure
This section discusses the structure of oneM2M requests and responses in the context of how they are defined in the oneM2M specifications.
Depending on the actual protocol binding that is used to send the requests and responses, the structure and the format of the requests and responses may differ. For example, when using the HTTP protocol binding, the requests and responses are formatted as HTTP messages, where some of the request's attributes are mapped to HTTP headers and URL parameters.
Requests
A oneM2M request is a structure of attribute values that used to specify the operation that is to be performed, the target resource, and the data that is to be processed. The following table lists some of the most common attributes that are used in a oneM2M request. Depending on the operation and application requirements there are more attributes that can be used in a request.
A full list of attributes can be found in the oneM2M specification TS-0004, clause 6.4.1 "Request primitive parameter data types".
| Attribute | Shortname | Description |
|---|---|---|
| operation | op | The operation that is to be performed. This can be one of the operations listed in the previous section. |
| to | to | The identifier of the resource that is the target of the request. |
| from | fr | The identifier of the originator of the request. |
| Request Identifier | rqi | A unique identifier for the request. |
| Release Version Indicator | rvi | The release version of the oneM2M specification that is used to process the request. |
| Content | pc | The data that is to be processed by the operation. This optional attribute is usually only used in CREATE, UPDATE, and NOTIFY operations. |
| Resource Type | ty | The type of the resource that is to be created. This optional attribute is only used in CREATE operations. |
| Result Content | rcn | The type of the content that is to be returned in the response. This optional attribute determines the presence and type of the response primitive content. |
Table 2: Common Request Attributes
Responses
Similar to requests, a oneM2M response is a structure of attribute values that is used to specify the result of the request processing. The following table lists some of the most common attributes that are used in a oneM2M response.
A full list of attributes can be found in the oneM2M specification TS-0004, clause 6.4.2 "Response primitive parameter data types".
| Attribute | Shortname | Description |
|---|---|---|
| to | to | The identifier of the resource that is the target of the response. This is usually the originator of the original request. |
| from | fr | The identifier of the sender of the response. This is usually the CSE's CSE-ID of the original request. |
| Request Identifier | rqi | The same unique identifier of the request that is being responded to. |
| Release Version Indicator | rvi | The release version of the oneM2M specification that was used to process the request. |
| Response Status Code | rsc | The response status code of the request processing. This status code indicates either the success of the operation or the reason for a failure. See TS-0004, clause 6.6 "Response status codes" for a full list of status codes. |
| Content | pc | The data that is the result of the request processing. The presence of this optional attribute depends on the |
Table 3: Common Response Attributes
Examples
RETRIEVE Request and Response
The following example shows a oneM2M request and response, formatted as JSON objects, to retrieve a <container> resource from a oneM2M CSE.
{
"to": "CmyAE",
"fr": "/id-in",
"rqi": "7878540125273236611",
"rvi": "4",
"rsc": 2000,
"pc": {
"m2m:cnt": {
"ri": "cnt6813592545172504041",
"rn": "aContainer",
"pi": "CmyAE",
"ty": 3,
"ct": "20240225T112600,086283",
"lt": "20240225T112600,086283",
"et": "20290223T112559,978109",
"cbs": 0,
"cni": 0,
"mni": 10,
"st": 0
}
}
}
CREATE Request and Response
The following example shows a oneM2M request and response, formatted as JSON objects, to create a <contentInstance> resource under a <container> resource.
{
"to": "CmyAE",
"fr": "/id-in",
"rqi": "7878540125273236611",
"rvi": "4",
"rsc": 2001,
"pc": {
"m2m:cin": {
"ri": "cin6813592545172504041",
"rn": "cin_4TvbcskOxs",
"pi": "cnt6813592545172504041",
"ty": 4,
"ct": "20240225T112600,231212",
"lt": "20240225T112600,231212",
"et": "20290223T112559,978109",
"st": 1,
"con": "23"
}
}
}
UPDATE Request and Response
The following example shows a oneM2M request and response, formatted as JSON objects, to update a <container> resource.
{
"to": "CmyAE",
"fr": "/id-in",
"rqi": "7878540125273236611",
"rvi": "4",
"rsc": 2004,
"pc": {
"m2m:cnt": {
"ri": "cnt6813592545172504041",
"rn": "aContainer",
"pi": "CmyAE",
"ty": 3,
"ct": "20240225T112600,086283",
"lt": "20240225T113900,034633",
"et": "20290223T112559,978109",
"cbs": 0,
"cni": 0,
"mni": 20,
"st": 0
}
}
}
DELETE Request and Response
The following example shows a oneM2M request and response, formatted as JSON objects, to delete a <container> resource.
NOTIFY Request and Response
The following example shows a oneM2M request and response, formatted as JSON objects, to send a notification to a oneM2M entity. In this example, a notification is sent to an Application Entity (AE) to inform it about a new content instance that has been created under a container.
{
"op": 5,
"to": "cse-in/CmyAE",
"fr": "/id-in",
"rqi": "7878540125273236611",
"rvi": "4",
"pc": {
"m2m:sgn": {
"nev": {
"net": 3,
"rep": {
"m2m:cin": {
"ri": "cin6813592545172504041",
"rn": "cin_4TvbcskOxs",
"pi": "cnt6813592545172504041",
"ty": 4,
"ct": "20240225T112600,231212",
"lt": "20240225T112600,231212",
"et": "20290223T112559,978109",
"st": 1,
"con": "23"
}
}
},
"sur": "/id-in/sub7616898474514005142"
}
}
}
by Andreas Kraft, 2024-02-25