View source for OM2M/one/REST API

__TOC__
== Install a REST client ==
* 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.
* The authentication is handle using a specific oneM2M header: '''X-M2M-Origin'''. This has to be specified in every request to identify the sender.

== Retrieve a resource == 
* HTTP request:
{{CTable}}
| Field||	Value
|-
| URL||	http://127.0.0.1:8080/~/in-cse
|-
| Method||	GET
|-
| Header||	X-M2M-Origin:  admin:admin <br> Accept:  application/xml
|-
| Body||	(empty)
|}

* HTTP response:
{{CTable}}
|Field||	Value
|-
|Status||	200 OK
|-
|Body||	<pre>
<?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>
</pre>
|}

== Create a "MY_SENSOR" application ==
* Send a HTTP request with the following parameters to create a '''MY_SENSOR''' application on the gateway.
{{CTable}}
* 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)
** '''X-M2M-NM''': the name of the resource to be created
|Field||	Value
|-
|URL||	http://127.0.0.1:8080/~/in-cse
|-
|Method||	POST
|-
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=2
|-
|Body||	<pre>
<om2m:ae xmlns:om2m="http://www.onem2m.org/xml/protocols" rn="MY_SENSOR" >
    <api>app-sensor</api>
    <lbl>Type/sensor Category/temperature Location/home</lbl>
    <rr>false</rr>
</om2m:ae></pre>
|}

* HTTP response:
{{CTable}}
|Field|| Value
|-
| Status || 201 Created
|-
|Headers || Content-Location: /in-cse/ae-CAE449907766
|-
| Body || <pre>
<?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>
</pre>
|}
<!--* 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"
** '''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:
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".
-->
* 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: 
{{CTable}}
|Field||	Value
|-
|URL||	http://127.0.0.1:8080/~/in-cse?fu=1&lbl=Type/sensor
|-
| Method||	GET
|-
| Header||  X-M2M-Origin:  admin:admin <br> Accept: application/xml
|-
|Body||	(empty)
|}

* HTTP response:
{{CTable}}
|Field||	Value
|-
|Status||	200 OK
|-
|Body||	<pre>
<?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></pre>
|}

== Create a DESCRIPTOR container ==
* Send a HTTP request with the following parameters to create a '''DESCRIPTOR''' container resource under the '''MY_SENSOR''' application.
{{CTable}}
|Field|| Value
|-
| URL||	http://127.0.0.1:8080/~/in-cse/in-name/MY_SENSOR
|-
| Method||	POST
|-
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=3
|-
|Body||	<pre>
<om2m:cnt xmlns:om2m="http://www.onem2m.org/xml/protocols" rn="DESCRIPTOR">
</om2m:cnt></pre>
|}

* HTTP response
{{CTable}}
|Field || Value
|-
| Status || 201 Created
|-
| Header || Content-Location: /in-cse/cnt-478855064
|-
| Body || <pre>
<?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>
</pre>
|}
<!--* As the AE, there is two ways to access the resource:
** '''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"-->
* 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.
{{CTable}}
| Field	|| Value
|-
| URL||	http://127.0.0.1:8080/~/in-cse/in-name/MY_SENSOR/DESCRIPTOR
|-
| Method|| POST
|-
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=4
|-
| Body||<pre>	
<om2m:cin xmlns:om2m="http://www.onem2m.org/xml/protocols">
    <cnf>application/xml</cnf>
    <con>
        &amp;lt;obj&amp;gt;
            &amp;lt;str name=&amp;quot;type&amp;quot; val=&amp;quot;Temperature_Sensor&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;op name=&amp;quot;getValue&amp;quot; href=&amp;quot;/in-cse/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;
        &amp;lt;/obj&amp;gt;
    </con>
</om2m:cin>
</pre>
|}
* 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.
{{CTable}}
|Field|| Value
|-
| URL|| http://127.0.0.1:8080/~/in-cse/in-name/MY_SENSOR
|-
| Method||  POST
|-
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=3 <br> X-M2M-NM: DATA
|-
|Body|| <pre>
<om2m:cnt xmlns:om2m="http://www.onem2m.org/xml/protocols">
</om2m:cnt></pre>
|}
* 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.
{{CTable}}
|Field||	Value
|-
|URL||	http://127.0.0.1:8080/~/in-cse/in-name/MY_SENSOR/DATA
|-
|Method||	POST
|-
|Header||	X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=4
|-
|Body|| <pre>	
<om2m:cin xmlns:om2m="http://www.onem2m.org/xml/protocols">
    <cnf>message</cnf>
    <con>
      &amp;lt;obj&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;category&amp;quot; val=&amp;quot;temperature &amp;quot;/&amp;gt;
        &amp;lt;int name=&amp;quot;data&amp;quot; val=&amp;quot;27&amp;quot;/&amp;gt;
        &amp;lt;int name=&amp;quot;unit&amp;quot; val=&amp;quot;celsius&amp;quot;/&amp;gt;
      &amp;lt;/obj&amp;gt;
    </con>
</om2m:cin>
</pre>
|}
* Check the created content instance on the web interface.

== Subscribe to MY_SENSOR data  ==
* Download the monitor server sample from this link: [https://www.laas.fr/projects/IOT/sites/www.laas.fr.projects.IOT/files/u77/monitor.jar Monitor].
* Start the Monitor server using the following command:
<pre>
> java -jar monitor.jar
</pre>
* The monitor starts listening on port=1400 and context=/monitor.
[[File:console-monitor.png|center|600px|thumb|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.
{{CTable}}
|Field||	Value
|-
|URL||	http://127.0.0.1:8080/~/in-cse/in-name/MY_SENSOR/DATA
|-
|Method||	POST
|-
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=23
|-
|Body||<pre>
<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></pre>
|}

* 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:

<pre>
<?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>
</pre>

* 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.