Mapping oneM2M Requests and Responses to HTTP
oneM2M defines a set of RESTful operations that can be used to access and manipulate resources in a oneM2M CSE. For the HTTP protocol these operations are mapped to HTTP methods and are described in Table 1.
This recipe focuses on HTTP which tends to be the first protocol that developers experiment with (before CoAP and MQTT).
| oneM2M Operation | HTTP Method | Description |
|---|---|---|
| CREATE | POST | Create a new resource |
| RETRIEVE | GET | Retrieve a resource |
| UPDATE | PUT | Update a resource |
| DELETE | DELETE | Delete a resource |
| NOTIFY | POST | Notify an AE, a CSE, or a resource |
Table 1: Mapping of oneM2M Operations to HTTP Methods
Attributes and Status Code Mappings
A oneM2M request contains request parameters and an optional primitive content. The request paramaters are mapped to either URL arguments or to HTTP header fields. The from request parameter, for example, is mapped to the X-M2M-Origin header while the resultContent (rcn) request parameter is added to the URL as an argument.
The request's to parameter is mapped to the path of the URL and the actual primitiveContent of a oneM2M request is put into an HTTP request's body.
The response to a oneM2M request contains a response status code and an optional primitive content. The response status code is mapped to the HTTP status code of the response. For example, the oneM2M Response Status Code 2000 is mapped to the HTTP status code 200 OK.
The primitive content is put into the body of the HTTP response.
This article can only give a short introduction to the mappings. For a complete mapping description your may have a look at the oneM2M Technical Specification TS-0009 - HTTP Protocol Binding.
Target Resource Identifier Mapping
The target resource's resource identifier of a request, i.e. the to request attribute, is mapped to the HTTP request URL's path.
For a resource identifier in CSE-relative format this is straight-forward, as the example below shows. But, if the resource identifier is in SP-relative or Absolute format the mapping is a bit more complicated. In oneM2M a resource identifier's scope is marked by the number of slashes preceding the resource identifier1. We cannot simply copy the resource identifier to the path because consectutive slashes are not allowed in URLs. Therefore, the leading slashes of the resource identifier are replaced by special character sequences.
For an SP-relative resource identifier the leading slash is replaced by ~/, and for an Absolute resource identifier the leading two slashes are replaced by _/.
The following examples show the different mappings.
- Resource Identifier :
cse-in/myAE/myCnt - HTTP : http://localhost:8080/
cse-in/myAE/myCnt
- Resource Identifier :
/cse-id/cse-in/myAE/myCnt - HTTP : http://localhost:8080/
~/cse-id/cse-in/myAE/myCnt
- Resource Identifier :
//sp-id/cse-id/cse-in/myAE/myCnt - HTTP : http://localhost:8080/
_/sp-id/cse-id/cse-in/myAE/myCnt
See also Resource Identifier Scopes and Formats for more details.
Requests
The following examples show various mappings of oneM2M requests to HTTP requests.
Note
In the examples we use a oneM2M <container> resource with the resource name myCnt located under the CSEbase cse-in.
We also use the originator CAdmin and the request ID 123 for all requests. In a real application, the originator should be the originator of the request, ie. an AE, and the request ID should be unique.
The requested release version is 4.
The CSE runs on the local port 8080.
General Request Flow
All oneM2M requests follow a simple request/response flow:
sequenceDiagram
participant Originator as oneM2M Originator
participant Receiver as oneM2M Receiver
Originator ->> Receiver: Send Request
Receiver -->> Receiver: Handle Request
Receiver ->> Originator: Send Response
Figure 1: General Request Flow
CREATE Request
This example shows how to create a new <container> resource under the CSEbase cse-in with the resource name myCnt.
Request
{
"op": 1, // CREATE
"to": "cse-in", // Target
"fr": "CAdmin", // Originator
"rqi": "123", // Request ID
"rvi": "4", // Specification version
"ty": 3, // Type
"pc": { // Primitive Content
"m2m:cnt": { // Container
"rn": "myCnt" // Resource Name
}
}
}
Response
{
"rsc": 2001, // Response Status Code
"to": "CAdmin", // Originator
"fr": "cse-in", // Target
"rqi": "123", // Request ID
"rvi": "4", // Specification version
"pc": { // Primitive Content
"m2m:cnt": {
"ty": 3, // Type
"rn": "myCnt", // Resource Name
"pi": "id-in", // Parent ID
"ri": "cnt3513897367629275974", // Resource ID
"ct": "20231105T141843,152179", // Creation Time
"lt": "20231105T141843,152179", // Last Modified Time
"et": "20281103T141843,161230", // Expiration Time
"cni": 0, // Current Number of Instances
"cbs": 0, // Current Byte Size
"st": 0 // State Tag
}
}
}
Request
POST /cse-in HTTP/1.1
Accept: application/json
Content-Type: application/json;ty=3
X-M2M-Origin: CAdmin
X-M2M-RI: 123
X-M2M-RVI: 4
{
"m2m:cnt": {
"rn": "myCnt"
}
}
Note, that the Content-Type ty parameter is set to 3 to indicate that the content is a <container> resource.
Response
HTTP/1.1 201 Created
Content-Type: application/json
X-M2M-RSC: 2001
X-M2M-RI: 123
X-M2M-RVI: 4
{
"m2m:cnt": {
"rn": "myCnt",
"ri": "cnt3513897367629275974",
"ct": "20231105T141843,152179",
"lt": "20231105T141843,152179",
"et": "20281103T141843,161230",
"pi": "id-in",
"ty": 3,
"cni": 0,
"cbs": 0,
"st": 0
}
}
RETRIEVE Request
This example shows how to retrieve the <container> resource with the resource name myCnt located under the CSEbase cse-in.
Request
{ "op": 2, // RETRIEVE
"to": "cse-in/myCnt", // Target
"fr": "CAdmin", // Originator
"rqi": "123", // Request ID
"rvi": "4", // Specification version
"ty": 3, // Type
"rcn": 1 // Result Content
}
Response
{
"rsc": 2000, // Response Status Code
"to": "CAdmin", // Originator
"fr": "cse-in", // Target
"rqi": "123", // Request ID
"rvi": "4", // Specification version
"pc": { // Primitive Content
"m2m:cnt": {
"ty": 3, // Type
"rn": "myCnt", // Resource Name
"pi": "id-in", // Parent ID
"ri": "cnt3513897367629275974", // Resource ID
"ct": "20231105T141843,152179", // Creation Time
"lt": "20231105T141843,152179", // Last Modified Time
"et": "20281103T141843,161230", // Expiration Time
"cni": 0, // Current Number of Instances
"cbs": 0, // Current Byte Size
"st": 0 // State Tag
}
}
}
Request
GET /cse-in/myCnt?rcn=1 HTTP/1.1
Accept: application/json
X-M2M-Origin: CAdmin
X-M2M-RI: 123
X-M2M-RVI: 4
Response
HTTP/1.1 200 OK
Content-Type: application/json
X-M2M-RSC: 2000
X-M2M-RI: 123
X-M2M-RVI: 4
{
"m2m:cnt": {
"rn": "myCnt",
"ri": "cnt3513897367629275974",
"ct": "20231105T141843,152179",
"lt": "20231105T141843,152179",
"et": "20281103T141843,161230",
"pi": "id-in",
"ty": 3,
"cni": 0,
"cbs": 0,
"st": 0
}
}
UPDATE Request
This example shows how to update the <container> resource with the resource name myCnt located under the CSEbase cse-in.
Request
{
"op": 3, // UPDATE
"to": "cse-in/myCnt", // Target
"fr": "CAdmin", // Originator
"rqi": "123", // Request ID
"rvi": "4", // Specification version
"ty": 3, // Type
"pc": { // Primitive Content
"m2m:cnt": { // Container
"lbl": [ // Labels
"aLabel"
]
}
}
}
Response
{
"rsc": 2004, // Response Status Code
"to": "CAdmin", // Originator
"fr": "cse-in", // Target
"rqi": "123", // Request ID
"rvi": "4", // Specification version
"pc": { // Primitive Content
"m2m:cnt": {
"ty": 3, // Type
"rn": "myCnt", // Resource Name
"pi": "id-in", // Parent ID
"ri": "cnt3513897367629275974", // Resource ID
"ct": "20231105T141843,152179", // Creation Time
"lt": "20231105T141843,152179", // Last Modified Time
"et": "20281103T141843,161230", // Expiration Time
"cni": 0, // Current Number of Instances
"cbs": 0, // Current Byte Size
"st": 0, // State Tag
"lbl": ["aLabel"] // Labels
}
}
}
Request
PUT /cse-in/myCnt HTTP/1.1
Accept: application/json
Content-Type: application/json
X-M2M-Origin: CAdmin
X-M2M-RI: 123
X-M2M-RVI: 4
{
"m2m:cnt": {
"lbl": ["aLabel"]
}
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
X-M2M-RSC: 2004
X-M2M-RI: 123
X-M2M-RVI: 4
{
"m2m:cnt": {
"rn": "myCnt",
"ri": "cnt3513897367629275974",
"ct": "20231105T141843,152179",
"lt": "20231105T141843,152179",
"et": "20281103T141843,161230",
"pi": "id-in",
"ty": 3,
"cni": 0,
"cbs": 0,
"st": 0,
"lbl": ["aLabel"]
}
}
DELETE Request
This example shows how to delete the <container> resource with the resource name myCnt located under the CSEbase cse-in.
Request
{
"op": 4, // DELETE
"to": "cse-in/myCnt", // Target
"fr": "CAdmin", // Originator
"rqi": "123", // Request ID
"rvi": "4", // Specification version
"ty": 3 // Type
}
Response
Request
DELETE /cse-in/myCnt HTTP/1.1
Accept: application/json
X-M2M-Origin: CAdmin
X-M2M-RI: 123
X-M2M-RVI: 4
Response
Summary
This article showed how oneM2M requests map to HTTP requests. Further details can be found in the oneM2M Technical Specification TS-0009 - HTTP Protocol Binding.
by Andreas Kraft, 2023-11-05
-
No leading slash means the resource identifier is in CSE-relative format, one leading slash means the resource identifier is in SP-relative format, and two leading slashes mean the resource identifier is in Absolute format. ↩