Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "OM2M/one/REST API"

< OM2M‎ | one
(Discover resources based on their search strings)
 
(18 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
__TOC__
 
__TOC__
== Install a rest client ==
+
== Install a REST client ==
 
* For this section, you need a REST client to send HTTP request (GET, POST, UPDATE, DELETE) to the OM2M platform.  
 
* For this section, you need a REST client to send HTTP request (GET, POST, UPDATE, DELETE) to the OM2M platform.  
* You can use Postman (http://www.getpostman.com) google chrome extension or any other REST client.
+
* Install Postman extension on google chrome browser: http://www.postman.com  
* The authentication is handle using a specific oneM2M header: '''X-M2M-Origin'''. This has to be specified in every request to identify the sender.
+
* The tutorial postman collection is available here: https://www.getpostman.com/collections/41fad4dcdaca7a90325e
  
 
== Retrieve a resource ==  
 
== Retrieve a resource ==  
Line 40: Line 40:
 
</pre>
 
</pre>
 
|}
 
|}
 +
 +
You can set the '''Accept''' header to '''application/json''' if you want a response in JSON format instead of XML.
  
 
== Create a "MY_SENSOR" application ==
 
== Create a "MY_SENSOR" application ==
Line 48: Line 50:
 
*** The format of the exchange, here "application/xml"
 
*** The format of the exchange, here "application/xml"
 
*** The resource type to be created, here "ty=2" (2 for AE, see oneM2M spec TS-0004 (V2.7.1), Table 6.3.4.2.1-1)
 
*** The resource type to be created, here "ty=2" (2 for AE, see oneM2M spec TS-0004 (V2.7.1), Table 6.3.4.2.1-1)
** '''X-M2M-NM''': the name of the resource to be created
+
 
 
|Field|| Value
 
|Field|| Value
 
|-
 
|-
Line 55: Line 57:
 
|Method|| POST
 
|Method|| POST
 
|-
 
|-
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=2 <br> X-M2M-NM: MY_SENSOR
+
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=2
 
|-
 
|-
 
|Body|| <pre>
 
|Body|| <pre>
<om2m:ae xmlns:om2m="http://www.onem2m.org/xml/protocols">
+
<m2m:ae xmlns:m2m="http://www.onem2m.org/xml/protocols" rn="MY_SENSOR" >
 
     <api>app-sensor</api>
 
     <api>app-sensor</api>
 
     <lbl>Type/sensor Category/temperature Location/home</lbl>
 
     <lbl>Type/sensor Category/temperature Location/home</lbl>
 
     <rr>false</rr>
 
     <rr>false</rr>
</om2m:ae></pre>
+
</m2m:ae></pre>
 
|}
 
|}
  
Line 89: Line 91:
 
</pre>
 
</pre>
 
|}
 
|}
* Here, the application has been created and can be accessed using 2 different URIs:  
+
<!--* Here, the application has been created and can be accessed using 2 different URIs:  
 
** '''Unstructured URI''': this URI is the '''ri''' node in the AE representation or present in the '''Content-Location''' header in the creation response "/<cse-id>/<id-of-the-resource>". In our case we have "/in-cse/ae-CAE449907766"
 
** '''Unstructured URI''': this URI is the '''ri''' node in the AE representation or present in the '''Content-Location''' header in the creation response "/<cse-id>/<id-of-the-resource>". In our case we have "/in-cse/ae-CAE449907766"
** '''Structured URI''': this URI use the names of the resources hierarchically to get the resource "/<cse-id>/<cse-name>/<hierarchy-of-resource-names>". Here we will simple have "/in-cse/in-name/MY-SENSOR".
+
** '''Structured URI''': this URI use the names of the resources hierarchically to get the resource "/<cse-id>/<cse-name>/<hierarchy-of-resource-names>". Here we will simply have "/in-cse/in-name/MY-SENSOR".
 
The difference between the unstructured URI and the structured one consists in the presence (or not) of the CSE name. Examples:
 
The difference between the unstructured URI and the structured one consists in the presence (or not) of the CSE name. Examples:
 
unstructured URI: "/<cse-id>/<id-of-the-resource>", for instance: "/in-cse/ae-123".
 
unstructured URI: "/<cse-id>/<id-of-the-resource>", for instance: "/in-cse/ae-123".
 
structured URI: "/in-cse/in-name/<hierarchy-of-resource-names>", for instance: "/in-cse/in-name/name1/name2/name3".
 
structured URI: "/in-cse/in-name/<hierarchy-of-resource-names>", for instance: "/in-cse/in-name/name1/name2/name3".
 +
-->
 
* You can check the created application on the web interface.
 
* You can check the created application on the web interface.
  
 
+
== Discover resources based on their labels ==
== Discover resources based on their search strings ==
+
 
* You can discover available resources based on their search strings using the discovery resource. The '''fu''' parameter (stands for "Filter Usage") indicate that it is a discovery request. The '''lbl''' ("Label")  indicate the specific label you what to filter.
 
* You can discover available resources based on their search strings using the discovery resource. The '''fu''' parameter (stands for "Filter Usage") indicate that it is a discovery request. The '''lbl''' ("Label")  indicate the specific label you what to filter.
 
* HTTP request:  
 
* HTTP request:  
Line 135: Line 137:
 
| Method|| POST
 
| Method|| POST
 
|-
 
|-
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=3 <br> X-M2M-NM: DESCRIPTOR
+
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=3
 
|-
 
|-
 
|Body|| <pre>
 
|Body|| <pre>
<om2m:cnt xmlns:om2m="http://www.onem2m.org/xml/protocols">
+
<m2m:cnt xmlns:m2m="http://www.onem2m.org/xml/protocols" rn="DESCRIPTOR">
</om2m:cnt></pre>
+
</m2m:cnt></pre>
 
|}
 
|}
  
Line 164: Line 166:
 
</pre>
 
</pre>
 
|}
 
|}
* As the AE, there is two ways to access the resource:
+
<!--* As the AE, there is two ways to access the resource:
 
** '''Unstructured URI''': which is '/in-cse/cnt-478855064'
 
** '''Unstructured URI''': which is '/in-cse/cnt-478855064'
** '''Structure URI''': which is the Structured URI of the AE plus the name of the container, in our case "/in-cse/in-name/MY_SENSOR/DESCRIPTOR"
+
** '''Structure URI''': which is the Structured URI of the AE plus the name of the container, in our case "/in-cse/in-name/MY_SENSOR/DESCRIPTOR"-->
 
* Check the created container on the web interface.
 
* Check the created container on the web interface.
  
Line 181: Line 183:
 
|-
 
|-
 
| Body||<pre>
 
| Body||<pre>
<om2m:cin xmlns:om2m="http://www.onem2m.org/xml/protocols">
+
<m2m:cin xmlns:m2m="http://www.onem2m.org/xml/protocols">
     <cnf>message</cnf>
+
     <cnf>application/xml</cnf>
 
     <con>
 
     <con>
 
         &amp;lt;obj&amp;gt;
 
         &amp;lt;obj&amp;gt;
Line 188: Line 190:
 
             &amp;lt;str name=&amp;quot;location&amp;quot; val=&amp;quot;Home&amp;quot;/&amp;gt;
 
             &amp;lt;str name=&amp;quot;location&amp;quot; val=&amp;quot;Home&amp;quot;/&amp;gt;
 
             &amp;lt;str name=&amp;quot;appId&amp;quot; val=&amp;quot;MY_SENSOR&amp;quot;/&amp;gt;
 
             &amp;lt;str name=&amp;quot;appId&amp;quot; val=&amp;quot;MY_SENSOR&amp;quot;/&amp;gt;
             &amp;lt;op name=&amp;quot;getValue&amp;quot; href=&amp;quot;/in-cse/MY_SENSOR/DATA/la&amp;quot;  
+
             &amp;lt;op name=&amp;quot;getValue&amp;quot; href=&amp;quot;/in-cse/in-name/MY_SENSOR/DATA/la&amp;quot;  
 
         in=&amp;quot;obix:Nil&amp;quot; out=&amp;quot;obix:Nil&amp;quot; is=&amp;quot;retrieve&amp;quot;/&amp;gt;
 
         in=&amp;quot;obix:Nil&amp;quot; out=&amp;quot;obix:Nil&amp;quot; is=&amp;quot;retrieve&amp;quot;/&amp;gt;
 
         &amp;lt;/obj&amp;gt;
 
         &amp;lt;/obj&amp;gt;
 
     </con>
 
     </con>
</om2m:cin>
+
</m2m:cin>
 
</pre>
 
</pre>
 
|}
 
|}
Line 206: Line 208:
 
| Method||  POST
 
| Method||  POST
 
|-
 
|-
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=3 <br> X-M2M-NM: DATA
+
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=3
 
|-
 
|-
 
|Body|| <pre>
 
|Body|| <pre>
<om2m:cnt xmlns:om2m="http://www.onem2m.org/xml/protocols">
+
<m2m:cnt xmlns:m2m="http://www.onem2m.org/xml/protocols" rn="DATA">
</om2m:cnt></pre>
+
</m2m:cnt></pre>
 
|}
 
|}
 
* Check the created container on the web interface.
 
* Check the created container on the web interface.
Line 226: Line 228:
 
|-
 
|-
 
|Body|| <pre>
 
|Body|| <pre>
<om2m:cin xmlns:om2m="http://www.onem2m.org/xml/protocols">
+
<m2m:cin xmlns:m2m="http://www.onem2m.org/xml/protocols">
 
     <cnf>message</cnf>
 
     <cnf>message</cnf>
 
     <con>
 
     <con>
Line 236: Line 238:
 
       &amp;lt;/obj&amp;gt;
 
       &amp;lt;/obj&amp;gt;
 
     </con>
 
     </con>
</om2m:cin>
+
</m2m:cin>
 
</pre>
 
</pre>
 
|}
 
|}
 
* Check the created content instance on the web interface.
 
* Check the created content instance on the web interface.
 +
 +
== Create a "MY_SENSOR" application using JSON ==
 +
* Since OM2M supports JSON, you can send an HTTP request with the following parameters to create a '''MY_SENSOR''' application on the gateway using JSON instead of XML.
 +
{{CTable}}
 +
|Field|| Value
 +
|-
 +
|URL|| http://127.0.0.1:8080/~/in-cse
 +
|-
 +
|Method|| POST
 +
|-
 +
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/json;ty=2
 +
|-
 +
|Body|| <pre>
 +
{
 +
  "m2m:ae": {
 +
    "api": "app-sensor",
 +
    "rr": "false",
 +
    "lbl": ["Type/sensor", "Category/temperature", "Location/home"],
 +
    "rn": "MY_SENSOR"
 +
  }
 +
}
 +
</pre>
 +
|}
 +
 +
You can interact with the system in the same way using JSON instead of XML with an equivalent of the XML body. (Be careful for the Labels to use a JSON array for instance: "lbl":"["label-1", "label-2"].)
 +
  
 
== Subscribe to MY_SENSOR data  ==
 
== Subscribe to MY_SENSOR data  ==
Line 259: Line 287:
 
|Method|| POST
 
|Method|| POST
 
|-
 
|-
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=23 <br> X-M2M-NM: SUB_MY_SENSOR
+
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=23
 
|-
 
|-
 
|Body||<pre>
 
|Body||<pre>
<m2m:sub xmlns:m2m="http://www.onem2m.org/xml/protocols">
+
<m2m:sub xmlns:m2m="http://www.onem2m.org/xml/protocols" rn="SUB_MY_SENSOR">
 
     <nu>http://localhost:1400/monitor</nu>
 
     <nu>http://localhost:1400/monitor</nu>
 
     <nct>2</nct>
 
     <nct>2</nct>
Line 298: Line 326:
 
* The Monitor receives a "Notify" resource including the new "ContentInstance".  
 
* The Monitor receives a "Notify" resource including the new "ContentInstance".  
 
* Remember that the "Notify" resource has a generic structure to support notifications for other type of resources such as "AE", "Container", "Group", "AccessControlPolicy", etc.
 
* Remember that the "Notify" resource has a generic structure to support notifications for other type of resources such as "AE", "Container", "Group", "AccessControlPolicy", etc.
 +
 +
= Short Names =
 +
* ae: Application Entity
 +
* cnt: Container
 +
* cin: Content Instance
 +
* sub: Subscription
 +
* sgn: Agregated Notification
 +
* rn: Resource Name
 +
* ty: Type
 +
* ri: Resource ID
 +
* pi: Parent Id
 +
* Acpi: Access Control Policies IDs
 +
* uril: URI List
 +
* ct: Creation Time
 +
* et: Expiration Time
 +
* lt: Last Modified Time
 +
* lbl: Label
 +
* cnf: Content Format
 +
* con: Content
 +
* mni: Maximum Number of Instance
 +
* st: State Tag
 +
* cs: Content Size
 +
* aei: Application Entity Id
 +
* api: Application Id
 +
* poa: Point of Access
 +
* rr: Request Reachability
 +
* nev: Notification Event
 +
* nep: Representation
 +
* sur: Subscription URI
 +
* Enc: Event Notification Criteria

Latest revision as of 11:07, 14 August 2020

Install a REST client

Retrieve a resource

  • HTTP request:
Field Value
URL http://127.0.0.1:8080/~/in-cse
Method GET
Header X-M2M-Origin: admin:admin
Accept: application/xml
Body (empty)
  • HTTP response:
Field Value
Status 200 OK
Body
<?xml version="1.0" encoding="UTF-8"?>
<m2m:cb xmlns:m2m="http://www.onem2m.org/xml/protocols" rn="in-name">
    <ty>5</ty>
    <ri>/in-cse</ri>
    <ct>20151104T150228</ct>
    <lt>20151104T150228</lt>
    <acpi>/in-cse/acp-563660429</acpi>
    <cst>1</cst>
    <csi>in-cse</csi>
    <srt>1 2 3 4 5 9 14 15 16 17 23</srt>
    <poa>http://127.0.0.1:8080/</poa>
</m2m:cb>

You can set the Accept header to application/json if you want a response in JSON format instead of XML.

Create a "MY_SENSOR" application

  • Send a HTTP request with the following parameters to create a MY_SENSOR application on the gateway.
  • In the creation we have two important headers:
    • Content-Type: this header has 2 informations seperated by a semicolon
      • The format of the exchange, here "application/xml"
      • The resource type to be created, here "ty=2" (2 for AE, see oneM2M spec TS-0004 (V2.7.1), Table 6.3.4.2.1-1)
Field Value
URL http://127.0.0.1:8080/~/in-cse
Method POST
Header X-M2M-Origin: admin:admin
Content-Type: application/xml;ty=2
Body
<m2m:ae xmlns:m2m="http://www.onem2m.org/xml/protocols" rn="MY_SENSOR" >
    <api>app-sensor</api>
    <lbl>Type/sensor Category/temperature Location/home</lbl>
    <rr>false</rr>
</m2m:ae>
  • HTTP response:
Field Value
Status 201 Created
Headers Content-Location: /in-cse/ae-CAE449907766
Body
<?xml version="1.0" encoding="UTF-8"?>
<m2m:ae xmlns:m2m="http://www.onem2m.org/xml/protocols" rn="MY_SENSOR">
    <ty>2</ty>
    <ri>ae-CAE449907766</ri>
    <pi>/in-cse</pi>
    <ct>20151104T151858</ct>
    <lt>20151104T151858</lt>
    <lbl>Type/sensor Category/temperature Location/home</lbl>
    <acpi>/in-cse/acp-89704715</acpi>
    <api>app-sensor</api>
    <aei>CAE449907766</aei>
    <rr>false</rr>
</m2m:ae>
  • You can check the created application on the web interface.

Discover resources based on their labels

  • You can discover available resources based on their search strings using the discovery resource. The fu parameter (stands for "Filter Usage") indicate that it is a discovery request. The lbl ("Label") indicate the specific label you what to filter.
  • HTTP request:
Field Value
URL http://127.0.0.1:8080/~/in-cse?fu=1&lbl=Type/sensor
Method GET
Header X-M2M-Origin: admin:admin
Accept: application/xml
Body (empty)
  • HTTP response:
Field Value
Status 200 OK
Body
<?xml version="1.0" encoding="UTF-8"?>
<m2m:disres xmlns:m2m="http://www.onem2m.org/xml/protocols">
    <ref ty="2"> <uri-of-the-resource> </ref>
</m2m:disres>

Create a DESCRIPTOR container

  • Send a HTTP request with the following parameters to create a DESCRIPTOR container resource under the MY_SENSOR application.
Field Value
URL http://127.0.0.1:8080/~/in-cse/in-name/MY_SENSOR
Method POST
Header X-M2M-Origin: admin:admin
Content-Type: application/xml;ty=3
Body
<m2m:cnt xmlns:m2m="http://www.onem2m.org/xml/protocols" rn="DESCRIPTOR">
</m2m:cnt>
  • HTTP response
Field Value
Status 201 Created
Header Content-Location: /in-cse/cnt-478855064
Body
<?xml version="1.0" encoding="UTF-8"?>
<m2m:cnt xmlns:m2m="http://www.onem2m.org/xml/protocols" rn="DESCRIPTOR">
    <ty>3</ty>
    <ri>cnt-478855064</ri>
    <pi>/in-cse/ae-CAE449907766</pi>
    <ct>20151104T155844</ct>
    <lt>20151104T155844</lt>
    <acpi>/in-cse/acp-89704715</acpi>
    <cni>0</cni>
    <cbs>0</cbs>
</m2m:cnt>
  • Check the created container on the web interface.

Create a description contentInstance

  • Send a HTTP request with the following parameters to create a description content instance resource under the "DESCRIPTOR" container.
Field Value
URL http://127.0.0.1:8080/~/in-cse/in-name/MY_SENSOR/DESCRIPTOR
Method POST
Header X-M2M-Origin: admin:admin
Content-Type: application/xml;ty=4
Body
	
<m2m:cin xmlns:m2m="http://www.onem2m.org/xml/protocols">
    <cnf>application/xml</cnf>
    <con>
        &lt;obj&gt;
            &lt;str name=&quot;type&quot; val=&quot;Temperature_Sensor&quot;/&gt;
            &lt;str name=&quot;location&quot; val=&quot;Home&quot;/&gt;
            &lt;str name=&quot;appId&quot; val=&quot;MY_SENSOR&quot;/&gt;
            &lt;op name=&quot;getValue&quot; href=&quot;/in-cse/in-name/MY_SENSOR/DATA/la&quot; 
         in=&quot;obix:Nil&quot; out=&quot;obix:Nil&quot; is=&quot;retrieve&quot;/&gt;
        &lt;/obj&gt;
    </con>
</m2m:cin>
  • Check the created content instance on the web interface.

Create a DATA container

  • Send a HTTP request with the following parameters to create a "DATA" container resource under the "MY_SENSOR" application.
Field Value
URL http://127.0.0.1:8080/~/in-cse/in-name/MY_SENSOR
Method POST
Header X-M2M-Origin: admin:admin
Content-Type: application/xml;ty=3
Body
<m2m:cnt xmlns:m2m="http://www.onem2m.org/xml/protocols" rn="DATA">
</m2m:cnt>
  • Check the created container on the web interface.

Create a data contentInstance

  • Send a HTTP request with the following parameters to create a data content instance resource under the "DATA" container.
Field Value
URL http://127.0.0.1:8080/~/in-cse/in-name/MY_SENSOR/DATA
Method POST
Header X-M2M-Origin: admin:admin
Content-Type: application/xml;ty=4
Body
	
<m2m:cin xmlns:m2m="http://www.onem2m.org/xml/protocols">
    <cnf>message</cnf>
    <con>
      &lt;obj&gt;
        &lt;str name=&quot;appId&quot; val=&quot;MY_SENSOR&quot;/&gt;
        &lt;str name=&quot;category&quot; val=&quot;temperature &quot;/&gt;
        &lt;int name=&quot;data&quot; val=&quot;27&quot;/&gt;
        &lt;int name=&quot;unit&quot; val=&quot;celsius&quot;/&gt;
      &lt;/obj&gt;
    </con>
</m2m:cin>
  • Check the created content instance on the web interface.

Create a "MY_SENSOR" application using JSON

  • Since OM2M supports JSON, you can send an HTTP request with the following parameters to create a MY_SENSOR application on the gateway using JSON instead of XML.
Field Value
URL http://127.0.0.1:8080/~/in-cse
Method POST
Header X-M2M-Origin: admin:admin
Content-Type: application/json;ty=2
Body
 {
   "m2m:ae": {
     "api": "app-sensor",
     "rr": "false",
     "lbl": ["Type/sensor", "Category/temperature", "Location/home"],
     "rn": "MY_SENSOR"
   }
 }

You can interact with the system in the same way using JSON instead of XML with an equivalent of the XML body. (Be careful for the Labels to use a JSON array for instance: "lbl":"["label-1", "label-2"].)


Subscribe to MY_SENSOR data

  • Download the monitor server sample from this link: Monitor.
  • Start the Monitor server using the following command:
> java -jar monitor.jar
  • The monitor starts listening on port=1400 and context=/monitor.
Monitor console: the server is started
  • Send a HTTP request with the following parameters to create a "Subscription" resource for receive asynchronously events from "MY_SENSOR" application.
  • The monitor listening URL (http://127.0.0.1:1400/monitor) should be added on the "nu" tag of the subscription representation.
Field Value
URL http://127.0.0.1:8080/~/in-cse/in-name/MY_SENSOR/DATA
Method POST
Header X-M2M-Origin: admin:admin
Content-Type: application/xml;ty=23
Body
<m2m:sub xmlns:m2m="http://www.onem2m.org/xml/protocols" rn="SUB_MY_SENSOR">
    <nu>http://localhost:1400/monitor</nu>
    <nct>2</nct>
</m2m:sub>
  • Check the created subscription on the web interface.
  • Create a new event content instance resource under the "DATA" container.
  • The new event is published to interested subscribers by the gateway.
  • Here is an example of the "Notify" XML representation:
<?xml version="1.0" encoding="UTF-8"?>
<m2m:sgn xmlns:m2m="http://www.onem2m.org/xml/protocols">
   <nev>
      <rep rn="cin_name1">
         <ty>4</ty>
         <ri>cin-46677406</ri>
         <pi>/in-cse/cnt-397256037</pi>
         <ct>20151104T162611</ct>
         <lt>20151104T162611</lt>
         <st>0</st>
         <cnf>message</cnf>
         <cs>11</cs>
         <con>hello world</con>
      </rep>
      <rss>1</rss>
   </nev>
   <sud>false</sud>
   <sur>/in-cse/in-name/MY_SENSOR/DATA/SUB_MY_SENSOR</sur>
</m2m:sgn>
  • The Monitor receives a "Notify" resource including the new "ContentInstance".
  • Remember that the "Notify" resource has a generic structure to support notifications for other type of resources such as "AE", "Container", "Group", "AccessControlPolicy", etc.

Short Names

  • ae: Application Entity
  • cnt: Container
  • cin: Content Instance
  • sub: Subscription
  • sgn: Agregated Notification
  • rn: Resource Name
  • ty: Type
  • ri: Resource ID
  • pi: Parent Id
  • Acpi: Access Control Policies IDs
  • uril: URI List
  • ct: Creation Time
  • et: Expiration Time
  • lt: Last Modified Time
  • lbl: Label
  • cnf: Content Format
  • con: Content
  • mni: Maximum Number of Instance
  • st: State Tag
  • cs: Content Size
  • aei: Application Entity Id
  • api: Application Id
  • poa: Point of Access
  • rr: Request Reachability
  • nev: Notification Event
  • nep: Representation
  • sur: Subscription URI
  • Enc: Event Notification Criteria

Copyright © Eclipse Foundation, Inc. All Rights Reserved.