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
(Created page with "Test")
 
Line 1: Line 1:
−
Test
+
__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 the "Client REST Simple" (https://chrome.google.com/webstore/detail/simple-rest-client/fhjcajmcbmldlhcimfajhfbgofnpcjmb), or Postman (http://www.getpostman.com) google chrome extension or any other rest client.
 +
[[File:rest-client.png|center|600px|thumb|Simple REST client inteface]]
 +
 
 +
* The authentification 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
 +
|-
 +
| 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-cse">
 +
    <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>
 +
|}
 +
 
 +
== 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.
 +
* HTTP request:
 +
{{CTable}}
 +
|Field|| Value
 +
|-
 +
|URL|| http://127.0.0.1:8080//in-cse?fu=1&lbl=my_app
 +
|-
 +
| Method|| GET
 +
|-
 +
| Header||  X-M2M-Origin:  admin:admin
 +
|-
 +
|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">/in-cse/ae_name1</ref>
 +
</m2m:disres></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, Table 6.3.3.2.11-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 <br> X-M2M-NM: MY_SENSOR
 +
|-
 +
|Body|| <pre>
 +
<om2m:ae xmlns:om2m="http://www.onem2m.org/xml/protocols">
 +
    <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. In our case we have "/in-cse/ae-CAE449907766"
 +
** '''Structured URI''': this URI use the names of the resources hierarchically to get the resource. Here we will simple have "/in-cse/MY-SENSOR".
 +
* You can check the created application on the web interface.
 +
 
 +
== 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/MY_SENSOR
 +
|-
 +
| Method|| POST
 +
|-
 +
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=3 <br> X-M2M-NM: DESCRIPTOR
 +
|-
 +
|Body|| <pre>
 +
<om2m:cnt xmlns:om2m="http://www.onem2m.org/xml/protocols">
 +
</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/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/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>message</cnf>
 +
    <con>
 +
        <obj>
 +
            <str name="type" val="Temperature_Sensor"/>
 +
            <str name="location" val="Home"/>
 +
            <str name="appId" val="MY_SENSOR"/>
 +
            <op name="getValue" href="/in-cse/MY_SENSOR/DATA/la"
 +
        in="obix:Nil" out="obix:Nil" is="retrieve"/>
 +
        </obj>
 +
    </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/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/om2m/gscl/applications/MY_SENSOR/containers/DATA/contentInstances
 +
|-
 +
|Method|| POST
 +
|-
 +
|Header|| Authorization:  Basic YWRtaW46YWRtaW4=
 +
|-
 +
|Body|| <pre>
 +
<obj>
 +
    <str name="appId" val="MY_SENSOR"/>
 +
    <str name="category" val="temperature "/>
 +
    <int name="data" val="27"/>
 +
    <int name="unit" val="celsius"/>
 +
</obj></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.dropbox.com/s/yjvuf7hnn5q83md/monitor-bin.zip?dl=0 Monitor-bin]. (The monitor source code is available here: [https://www.dropbox.com/s/y95qx9dn9rr3tfm/Monitor.java?dl=0 Monitor.java ]).
 +
* Extract the rar file.
 +
* You can configure the Monitor listening port and context using the "config.properties"
 +
* Start the Monitor server using the following command:
 +
<pre>
 +
> java -jar monitor.jar
 +
</pre>
 +
* By default 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/om2m//in-cse/MY_SENSOR/DATA
 +
|-
 +
|Method|| POST
 +
|-
 +
| Header||  X-M2M-Origin: admin:admin <br> Content-Type: application/xml;ty=23 <br> X-M2M-NM: SUB_MY_SENSOR
 +
|-
 +
|Body||<pre>
 +
<m2m:sub xmlns:m2m="http://www.onem2m.org/xml/protocols">
 +
    <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/MY_SENSOR/DATA/SUB_MY_SENSOR</sur>
 +
</m2m:sgn>
 +
</pre>
 +
 
 +
* The Monitor receives a "Notify" resource including the new "ContentInstance" encoded in Base64.
 +
* Remember that the "Notify" resource has a generic structure to support notifications for other type of resources such as "AE", "Container", "Group", AccessRight, etc.

Revision as of 11:28, 4 November 2015

Install a rest client

Simple REST client inteface
  • The authentification 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:
Field Value
URL http://127.0.0.1:8080//in-cse
Method GET
Header X-M2M-Origin: admin:admin
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-cse">
    <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>

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.
  • HTTP request:
Field Value
URL http://127.0.0.1:8080//in-cse?fu=1&lbl=my_app
Method GET
Header X-M2M-Origin: admin:admin
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">/in-cse/ae_name1</ref>
</m2m:disres>

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, Table 6.3.3.2.11-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
Content-Type: application/xml;ty=2
X-M2M-NM: MY_SENSOR
Body 
<om2m:ae xmlns:om2m="http://www.onem2m.org/xml/protocols">
    <api>app-sensor</api>
    <lbl>Type/sensor Category/temperature Location/home</lbl>
    <rr>false</rr>
</om2m: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>
  • 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. In our case we have "/in-cse/ae-CAE449907766"
    • Structured URI: this URI use the names of the resources hierarchically to get the resource. Here we will simple have "/in-cse/MY-SENSOR".
  • You can check the created application on the web interface.

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/MY_SENSOR
Method POST
Header X-M2M-Origin: admin:admin
Content-Type: application/xml;ty=3
X-M2M-NM: DESCRIPTOR
Body 
<om2m:cnt xmlns:om2m="http://www.onem2m.org/xml/protocols">
</om2m: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>
  • 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/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.
Field Value
URL http://127.0.0.1:8080//in-cse/MY_SENSOR/DESCRIPTOR
Method POST
Header X-M2M-Origin: admin:admin
Content-Type: application/xml;ty=4
Body 
	
<om2m:cin xmlns:om2m="http://www.onem2m.org/xml/protocols">
    <cnf>message</cnf>
    <con>
        <obj>
            <str name="type" val="Temperature_Sensor"/>
            <str name="location" val="Home"/>
            <str name="appId" val="MY_SENSOR"/>
            <op name="getValue" href="/in-cse/MY_SENSOR/DATA/la" 
         in="obix:Nil" out="obix:Nil" is="retrieve"/>
        </obj>
    </con>
</om2m: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/MY_SENSOR
Method POST
Header X-M2M-Origin: admin:admin
Content-Type: application/xml;ty=3
X-M2M-NM: DATA
Body 
<om2m:cnt xmlns:om2m="http://www.onem2m.org/xml/protocols">
</om2m: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/om2m/gscl/applications/MY_SENSOR/containers/DATA/contentInstances
Method POST
Header Authorization: Basic YWRtaW46YWRtaW4=
Body 
	
<obj>
     <str name="appId" val="MY_SENSOR"/>
     <str name="category" val="temperature "/>
     <int name="data" val="27"/>
     <int name="unit" val="celsius"/>
</obj>
  • Check the created content instance on the web interface.

Subscribe to MY_SENSOR data

  • Download the monitor server sample from this link: Monitor-bin. (The monitor source code is available here: Monitor.java ).
  • Extract the rar file.
  • You can configure the Monitor listening port and context using the "config.properties"
  • Start the Monitor server using the following command:
> java -jar monitor.jar
  • By default 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/om2m//in-cse/MY_SENSOR/DATA
Method POST
Header X-M2M-Origin: admin:admin
Content-Type: application/xml;ty=23
X-M2M-NM: SUB_MY_SENSOR
Body 
<m2m:sub xmlns:m2m="http://www.onem2m.org/xml/protocols">
    <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/MY_SENSOR/DATA/SUB_MY_SENSOR</sur>
</m2m:sgn>
  • The Monitor receives a "Notify" resource including the new "ContentInstance" encoded in Base64.
  • Remember that the "Notify" resource has a generic structure to support notifications for other type of resources such as "AE", "Container", "Group", AccessRight, etc.
Retrieved from "https://wiki.eclipse.org/index.php?title=OM2M/one/REST_API&oldid=393429"

Back to the top