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.
Difference between revisions of "OM2M/REST API"
< OM2M
(→Subscribe to MY_SENSOR data) |
(→Subscribe to MY_SENSOR data) |
||
(10 intermediate revisions by one other user not shown) | |||
Line 5: | Line 5: | ||
[[File:rest-client.png|center|600px|thumb|Simple REST client inteface]] | [[File:rest-client.png|center|600px|thumb|Simple REST client inteface]] | ||
− | * OM2M supports Basic access authentication to enforce access controls to web resources. Client username/password must be encoded to base64 then entered as a Basic Authorization header. You can use www.base64encode.org for base64 encryption. e.g. base64(admin | + | * OM2M supports Basic access authentication to enforce access controls to web resources. Client username/password must be encoded to base64 then entered as a Basic Authorization header. You can use www.base64encode.org for base64 encryption. e.g. base64(admin:admin) = YWRtaW46YWRtaW4= |
== Retrieve a resource == | == Retrieve a resource == | ||
Line 16: | Line 16: | ||
| Method|| GET | | Method|| GET | ||
|- | |- | ||
− | | Header|| Authorization: Basic | + | | Header|| Authorization: Basic YWRtaW46YWRtaW4= |
|- | |- | ||
| Body|| (empty) | | Body|| (empty) | ||
Line 57: | Line 57: | ||
| Method|| GET | | Method|| GET | ||
|- | |- | ||
− | |Header|| Authorization: Basic | + | |Header|| Authorization: Basic YWRtaW46YWRtaW4= |
|- | |- | ||
|Body|| (empty) | |Body|| (empty) | ||
Line 87: | Line 87: | ||
|Method|| POST | |Method|| POST | ||
|- | |- | ||
− | |Header|| Authorization: Basic | + | |Header|| Authorization: Basic YWRtaW46YWRtaW4= |
|- | |- | ||
|Body|| <pre> | |Body|| <pre> | ||
Line 110: | Line 110: | ||
| Method|| POST | | Method|| POST | ||
|- | |- | ||
− | |Header|| Authorization: Basic | + | |Header|| Authorization: Basic YWRtaW46YWRtaW4= |
|- | |- | ||
|Body|| <pre> | |Body|| <pre> | ||
Line 127: | Line 127: | ||
| Method|| POST | | Method|| POST | ||
|- | |- | ||
− | | Header|| Authorization: Basic | + | | Header|| Authorization: Basic YWRtaW46YWRtaW4= |
|- | |- | ||
| Body|| | | Body|| | ||
Line 151: | Line 151: | ||
|Method|| POST | |Method|| POST | ||
|- | |- | ||
− | |Header|| Authorization: Basic | + | |Header|| Authorization: Basic YWRtaW46YWRtaW4= |
|- | |- | ||
|Body|| <pre> | |Body|| <pre> | ||
Line 168: | Line 168: | ||
|Method|| POST | |Method|| POST | ||
|- | |- | ||
− | |Header|| Authorization: Basic | + | |Header|| Authorization: Basic YWRtaW46YWRtaW4= |
|- | |- | ||
|Body|| <pre> | |Body|| <pre> | ||
Line 184: | Line 184: | ||
== Subscribe to MY_SENSOR data == | == Subscribe to MY_SENSOR data == | ||
− | * Download the monitor server sample from this link: [https:// | + | * 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. | * Extract the rar file. | ||
* You can configure the Monitor listening port and context using the "config.properties" | * You can configure the Monitor listening port and context using the "config.properties" | ||
Line 203: | Line 203: | ||
|Method|| POST | |Method|| POST | ||
|- | |- | ||
− | |Header|| Authorization: Basic | + | |Header|| Authorization: Basic YWRtaW46YWRtaW4= |
|- | |- | ||
|Body||<pre> | |Body||<pre> | ||
Line 216: | Line 216: | ||
* Create a new event content instance resource under the "DATA" container. | * Create a new event content instance resource under the "DATA" container. | ||
* The new event is published to interested subscribers by the gateway. | * The new event is published to interested subscribers by the gateway. | ||
− | * | + | * Here is an example of the "Notify" XML representation: |
− | + | ||
<pre> | <pre> | ||
Line 229: | Line 228: | ||
</pre> | </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 "Application", "Container", "Group", AccessRight, etc. | ||
* You should see a message box, opened by the monitor, displaying the received event. | * You should see a message box, opened by the monitor, displaying the received event. | ||
[[File:monitor-notif.png|center|600px|thumb|Notification received by the monitor]] | [[File:monitor-notif.png|center|600px|thumb|Notification received by the monitor]] | ||
Line 242: | Line 243: | ||
</om2m:subscription> | </om2m:subscription> | ||
</pre> | </pre> | ||
− | |||
− | * In this case, the monitor will receive a "Notify" resource including directly the content. | + | * In this case, the monitor will receive a "Notify" resource including directly the "content" encoded in Base64. |
Latest revision as of 11:42, 27 November 2014
Contents
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.
- OM2M supports Basic access authentication to enforce access controls to web resources. Client username/password must be encoded to base64 then entered as a Basic Authorization header. You can use www.base64encode.org for base64 encryption. e.g. base64(admin:admin) = YWRtaW46YWRtaW4=
Retrieve a resource
- HTTP request:
Field | Value |
URL | http://127.0.0.1:8080/om2m/gscl |
Method | GET |
Header | Authorization: Basic YWRtaW46YWRtaW4= |
Body | (empty) |
- HTTP response:
Field | Value |
Status | 200 OK |
Body | <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <om2m:sclBase xmlns:om2m="http://uri.etsi.org/m2m" xmlns:xmime="http://www.w3.org/2005/05/xmlmime"> <om2m:accessRightID>gscl/accessRights/AR_ADMIN</om2m:accessRightID> <om2m:searchStrings> <om2m:searchString>ResourceType/SclBase</om2m:searchString> <om2m:searchString>ResourceID/gscl</om2m:searchString> </om2m:searchStrings> <om2m:creationTime>2014-04-07T14:45:33.935+02:00</om2m:creationTime> <om2m:lastModifiedTime>2014-04-07T14:45:33.991+02:00</om2m:lastModifiedTime> <om2m:sclsReference>gscl/scls</om2m:sclsReference> <om2m:applicationsReference>gscl/applications</om2m:applicationsReference> <om2m:containersReference>gscl/containers</om2m:containersReference> <om2m:groupsReference>gscl/groups</om2m:groupsReference> <om2m:accessRightsReference>gscl/accessRights</om2m:accessRightsReference> <om2m:subscriptionsReference>gscl/subscriptions</om2m:subscriptionsReference> <om2m:discoveryReference>gscl/discovery</om2m:discoveryReference> </om2m:sclBase> |
Discover resources based on their search strings
- You can discover available resources based on their search strings using the discovery resource.
- HTTP request:
Field | Value |
URL | http://127.0.0.1:8080/om2m/gscl/discovery?searchString=resourcetype/sclbase |
Method | GET |
Header | Authorization: Basic YWRtaW46YWRtaW4= |
Body | (empty) |
- HTTP response:
Field | Value |
Status | 200 OK |
Body | <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <om2m:discovery xmlns:om2m="http://uri.etsi.org/m2m" xmlns:xmime="http://www.w3.org/2005/05/xmlmime"> <om2m:matchSize>1</om2m:matchSize> <om2m:discoveryURI> <reference>gscl</reference> </om2m:discoveryURI> </om2m:discovery> |
Create a "MY_SENSOR" application
- Send a HTTP request with the following parameters to create a "MY_SENSOR" application on the gateway.
Field | Value |
URL | http://127.0.0.1:8080/om2m/gscl/applications |
Method | POST |
Header | Authorization: Basic YWRtaW46YWRtaW4= |
Body | <om2m:application xmlns:om2m="http://uri.etsi.org/m2m" appId="MY_SENSOR"> <om2m:searchStrings> <om2m:searchString>Type/sensor</om2m:searchString> <om2m:searchString>Category/temperature</om2m:searchString> <om2m:searchString>Location/Home</om2m:searchString> </om2m:searchStrings> </om2m:application> |
- 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
Field | Value |
URL | http://127.0.0.1:8080/om2m/gscl/applications/MY_SENSOR/containers |
Method | POST |
Header | Authorization: Basic YWRtaW46YWRtaW4= |
Body | <om2m:container xmlns:om2m="http://uri.etsi.org/m2m" om2m:id="DESCRIPTOR"> </om2m:container> |
- 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/om2m/gscl/applications/MY_SENSOR/containers/DESCRIPTOR/contentInstances |
Method | POST |
Header | Authorization: Basic YWRtaW46YWRtaW4= |
Body |
<obj> <str name="type" val="Temperature_Sensor"/> <str name="location" val="Home"/> <str name="appId" val="MY_SENSOR"/> <op name="getValue" href="gscl/applications/MY_SENSOR/containers/DATA/contentInstances/latest/content" in="obix:Nil" out="obix:Nil" is="retrieve"/> </obj> |
- 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/om2m/gscl/applications/MY_SENSOR/containers |
Method | POST |
Header | Authorization: Basic YWRtaW46YWRtaW4= |
Body | <om2m:container xmlns:om2m="http://uri.etsi.org/m2m" om2m:id="DATA"> </om2m:container> |
- 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.
- Click on the "getValue" button to retrieve the created sensor data.
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.
- 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 "om2m:contact" tag of the subscription representation.
Field | Value |
URL | http://127.0.0.1:8080/om2m/gscl/applications/MY_SENSOR/containers/DATA/contentInstances/subscriptions |
Method | POST |
Header | Authorization: Basic YWRtaW46YWRtaW4= |
Body | <om2m:subscription xmlns:om2m="http://uri.etsi.org/m2m"> <om2m:contact>http://127.0.0.1:1400/monitor</om2m:contact> </om2m:subscription> |
- 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:
<om2m:notify xmlns:om2m="http://uri.etsi.org/m2m" xmlns:xmime="http://www.w3.org/2005/05/xmlmime"> <om2m:statusCode>STATUS_CREATED</om2m:statusCode> <om2m:representation xmime:contentType="application/xml">Base64-encoded contentInstance</om2m:representation> <om2m:subscriptionReference> nscl/applications/MY_SENSOR/containers/DATA/contentInstances/subscriptions/SUB_13242383 </om2m:subscriptionReference> </om2m:notify>
- 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 "Application", "Container", "Group", AccessRight, etc.
- You should see a message box, opened by the monitor, displaying the received event.
- You can simplify the received Notify resource structure by creating a personalized subscription with filterCriteria IfMatch tag like this:
<om2m:subscription xmlns:om2m="http://uri.etsi.org/m2m"> <om2m:filterCriteria> <ifMatch>content</ifMatch> </om2m:filterCriteria> <om2m:contact>http://127.0.0.1:1400/monitor</om2m:contact> </om2m:subscription>
- In this case, the monitor will receive a "Notify" resource including directly the "content" encoded in Base64.