oneM2M REST API

oneM2M exploits the Representational State Transfer (REST) software architectural style for its communication between client and server (i.e. its various entities (AE,CSE)).
In the REST style, every object on the server is represented in the form of a resource and its resource representation is accessible by a URI (Uniform Resource Identifier). A resource representation has the state and content of the resource. It can be in XML, JSON, CBOR etc. formats.

For an M2M application provider to get started, following resources are to be used:

For an M2M application provider to get started, refer below:

1. For basic understanding of CSFs, request/response and resources, read below mentioned chapters and clauses from TS-0001:
   • Chapter 1 to 5
   • Chapter 6 - section 6.1
   • Chapter 8 - section 8.1 first 4 pages
   • Chapter 9 - section 9.5.0
2. For registration of application on CCSP Platform: <AE> resource: Application Entity resource, Refer oneM2M TS-0001 clause 9.6.5 and TS-0004 clause 7.4.5.
3. For container for data instances: <container> resource: Refer oneM2M TS-0001 clause 9.6.6 and TS-0004 clause 7.4.6.
4. For data instances: <contentInstance> resource: Refer oneM2M TS-0001 clause 9.6.7 and TS-0004 clause 7.4.7.
5. For subscription for any events on any resources: <subscription> resource: Refer oneM2M TS-0001 clause 9.6.8 and TS-0004 clause 7.4.8.

On these resources CRUD-N operations can be performed where CRUD-N is CREATE, RETRIEVE, UPDATE, DELETE and NOTIFY
For accessing oneM2M release 3 specifications: Click oneM2M Release 3 specifications: (e.g. TS-0001 (for architecture), TS-0004 (Service layer core protocol)

oneM2M Developer Guides

oneM2M has developed set of developer guides to enable M2M application developers to develop application fast . It also provide details of the RUD-N operations usage for accessing the CCSP.

1. oneM2M Developer Guide with HTTP protocol binding:
   https://wiki.onem2m.org/images/e/ea/TR-0025-Application_Developer_Guide-V2_0_3.pdf
2. oneM2M Developer Guide with CoAP protocol binding:
   https://wiki.onem2m.org/images/b/be/TR-0034-Developer_Guide_CoAP_binding-long_polling_for_temperature_monitori-V2_1_0.pdf
3. oneM2M Developer Guide with MQTT protocol binding:
   https://wiki.onem2m.org/images/7/72/TR-0037-Smart_Farm-Example_using_MQTT_Binding-v_2_0_0.pdf
4. oneM2M Developer Guide for security:
   https://wiki.onem2m.org/images/0/0a/TR-0038-Developer_guide-Implementing_security_example-V0_5_0.pdf

Brief guide for sending oneM2M request using HTTP protocol binding

oneM2M Mandatory Request Headers

• X-M2M-RI: Represents unique request identifier
• X-M2M-Origin: Represents identifier of originator i.e. AE identifier or CSE identifier
• X-M2M-RVI: Represents oneM2M release version

oneM2M Mandatory Response Headers

• X-M2M-RSC: Represents Response Status Code
• X-M2M-RI: Represents unique request identifier

For complete details on oneM2M response status codes mapping with HTTP status code, refer TS-0009 clause 6.3.2.

Common oneM2M Response status codes mapping with HTTP status codes

Example oneM2M HTTP requests:

Example: <AE> resource: Application Entity Registration HTTP Request:

    POST /<registrarCseBaseResourceId> HTTP/1.1  
    Host: <registrarUrl> 
    X-M2M-Origin: <AE-ID> 
    Content-Type: application/json;ty=2  
    X-M2M-RI: <AnyUniqueIdentifier>  
    X-M2M-RVI: 3
    Accept: application/json 
        
    { 
        "m2m:ae" : { 
        "api" : "<app-ID>",
        "srv" : ["2a","3"], 
        "rr" : true, 
        "lbl" : ["<labelsToDiscoverthisAE>"], 
        "rn" : "<resourceNameforAE>", 
        "poa": [ "http://<ADN-AE-IP:PORT>" ],
        "acpi": [ "<ACP-Resource-Id*>" ]
        } 
    }
    

Example: <container> resource: CREATE <container> resource HTTP Request:

    POST/<AE-ID> HTTP/1.1
    Host: <registrarUrl>
    X-M2M-Origin: <AE-ID>
    Content-Type: application/json;ty=3
    X-M2M-RI: <AnyUniqueIdentifier>
    X-M2M-RVI: 3
    Accept: application/json 

    {
        "m2m:cnt": {
            "lbl": ["<labelsToDiscoverthisContainer>"],
            "rn": "<resourceNameforContainer>",
            "acpi": ["<ACP-Resource-Id>"],
        }
    }

Example: <subscription> resource: CREATE <subscription> resource HTTP Request:

    POST /
<Container-ResourceId>
 HTTP/1.1  
    Host: <registrarUrl>  
    X-M2M-Origin: <AE-ID> 
    Content-Type: application/json;ty=23  
    X-M2M-RI: <AnyUniqueIdentifier> 
    X-M2M-RVI: 3
    Accept: application/json 
        
    { 
        "m2m:sub" : { 
        "rn" : "<resourceNameforSubscription>", 
        "acpi": ["<ACP-Resource-Id>"],
        "enc" : { 
            "net" : [ 3 ] 
        }, 
        "nu" : [ "<ADN-AE Notification Handler URL>?ct=json"], 
        "nct" : 1 
        } 
    } 

Example: <contentInstance> resource: CREATE <contentInstance> resource HTTP Request:

    POST /
<Container-ResourceId>
 HTTP/1.1  
        Host: <registrarUrl>  
        X-M2M-Origin: <AE-ID> 
        Content-Type: application/json;ty=4  
        X-M2M-RI: <AnyUniqueIdentifier>  
        X-M2M-RVI: 3
        Accept: application/json 
            
        { 
            "m2m:cin" : { 
            "con" : "OFF" 
        }
    }

Resource tree example:

Resource Short Name and Long Name Mapping: