9.2 KiB
Overview REST API
Introduction
This document gives a quick overview on how the external interfaces of an OpenMTC Gateway can be used to create new resources within an OpenMTC M2M system. Based on the same external interface, it is also shown how data can be retrieved from it. In general, all functionality of a Gateway is exposed via the resource tree. This resource tree is accessible in a RESTful manner through a HTTP interface. Thus, all examples in this document can be performed with standard off-the-shelve HTTP client software (curl, postman).
HTTP Requests and Responses as Given in this Text
Within the step-by-step guide further below in this text, each HTTP request and response are shown as their actual textual representation -- unimportant details are omitted.
A short (theoretical) example will help you to understand this.
Request
GET /some-example HTTP/1.1
Host: localhost:8000
This example, describes a GET request, based on HTTP/1.1, which is
send to the host localhost at port 8000 and requests the resource
/some-example.
Another example, outlines how a POST request will look like. Here,
an HTTP/1.1-based POST request will send the below specified JSON to
host localhost at port 8000 and requests to send it to resource
/some-example.
Request
POST /some-example HTTP/1.1
Host: localhost:8000
Content-Type: application/vnd.onem2m-res+json
{
"some-data": "some-string-value"
}
Example usage of HTTP clients
To be able to send the (theoretical) requests, given in the last subsection, cURL may be used, which is a command line program usable as HTTP client.
Retrieve a resource
curl -X GET localhost:8000/some-example
Here, the request command GET is send to localhost at port 8000,
requesting the resource "/some-example". If data was successfully
retrieved, by this, it will be printed to STDOUT.
Push plain text data to a resource
curl -X POST localhost:8000/some-example \
-H "Content-Type: application/vnd.onem2m-res+json" \
-d '{ "some-data": "some-string-value" }'
Here, plain text (JSON) data (-d) is pushed to the resource
"/some-example", by using the HTTP request command POST. Note that
the content type of the given data is specified via an additional HTTP
header (-H). If the provided JSON was successfully uploaded, a new
content instance for this resource is provided.
Push base64 encoded data to a resource
Sometimes, it is needed to encode given data -- for example a JSON -- as a base64 string. This can be done, at the command line, in the following way:
echo '{ "some-data": "some-string-value" }' | base64
Which will return following base64 encoded string:
eyAic29tZS1kYXRhIjogInNvbWUtc3RyaW5nLXZhbHVlIiB9Cg==
Pushing the same data as from the last subsection as a base64 encoded string will work like this:
curl -X POST localhost:8000/some-example \
-H "Content-Type: application/vnd.onem2m-res+json" \
-d 'eyAic29tZS1kYXRhIjogInNvbWUtc3RyaW5nLXZhbHVlIiB9Cg=='
If you need to do this as a single line command, just combine the two last commands in the following way:
curl -X POST localhost:8000/some-example \
-H "Content-Type: application/vnd.onem2m-res+json" \
-d $(echo '{ "some-data": "some-string-value" }' | base64)
A step-by-step Guide for OpenMTC's Rest API
Step 1: Create a new application entity within a given OpenMTC Gateway: AE creation.
Step 2: Check the stored information about your newly created application entity: Application Resource Retrieval.
Step 3: To be able to structure information provided by your newly created application entity, you should create a new oneM2M container within the hierarchy of your application: Create an Application Resource.
Step 4: Check whether your newly created oneM2M container was created correctly: Retrieve Information of a Specific Container Resource.
Step 5: Push new data (content instance) to your newly created application container. If your new content instance is supposed to store plain text value: Create plain text value Content Instance. If your new content instance is supposed to store base64-encoded values: Create base64-encoded Content Instance.
Step 6: Finally, check whether your data (content instance) was pushed correctly: Retrieve Latest Content Instances.
Create an Application Resource
Request
POST /onem2m
Host: localhost:8000
Content-Type: application/vnd.onem2m-res+json
{
"m2m:ae": {
"rn": "EXAMPLE_APP_NAME",
"api": "placeholder",
"rr": "TRUE"
}
}
Response
{
"m2m:ae": {
"ri":"ae1",
"nl":"dummy",
"rr":true,
"ty":2,
"et":"2017-03-02T16:46:13.350093+00:00",
"lt":"2017-03-02T16:12:53.350093+00:00",
"api":"placeholder",
"aei":"C1",
"pi":"cb0",
"rn":"EXAMPLE_APP_NAME",
"ct":"2017-03-02T16:12:53.350093+00:00"
}
}
Retrieve Information of a Specific Application Resource
Request
GET /onem2m/EXAMPLE_APP_NAME HTTP/1.1
Host: localhost:8000
Response
{
"m2m:ae": {
"ri":"ae0",
"nl":"dummy",
"rr":true,
"ty":2,
"et":"2017-03-02T16:54:10.097197+00:00",
"ch": [{
"typ":3,"nm":"EXAMPLE_CONTAINER_NAME",
"val":"cnt0"
}],
"lt":"2017-03-02T16:20:50.097197+00:00",
"api":"placeholder",
"aei":"C0",
"pi":"cb0",
"rn":"EXAMPLE_APP_NAME",
"ct":"2017-03-02T16:20:50.097197+00:00"
}
}
Create a Container Resource
Request
POST / HTTP/1.1
Host: localhost:8000
Content-Type: application/vnd.onem2m-res+json
{ "m2m:cnt": {
"rn": "EXAMPLE_CONTAINER_NAME"
}
}
Response
{
"m2m:cnt": {
"cr":"nobody",
"et":"2017-03-02T16:54:19.216702+00:00",
"ty":3,
"lt":"2017-03-02T16:20:59.216702+00:00",
"rn":"EXAMPLE_CONTAINER_NAME",
"ct":"2017-03-02T16:20:59.216702+00:00",
"ri":"cnt0",
"cni":0,
"cbs":0,
"pi":"ae0",
"st":"0"
}
}
Retrieve Information of a Specific Container Resource
Request
GET /onem2m/EXAMPLE_APP_NAME/EXAMPLE_CONTAINER_NAME HTTP/1.1
Host: localhost:8000
Response
{
"m2m:cnt": {
"cr":"nobody",
"et":"2017-03-02T16:54:19.216702+00:00",
"ty":3,
"lt":"2017-03-02T16:20:59.216702+00:00",
"rn":"EXAMPLE_CONTAINER_NAME",
"ct":"2017-03-02T16:20:59.216702+00:00",
"ri":"cnt0",
"cni":0,
"cbs":0,
"pi":"ae0",
"st":"0"
}
}
Create a Plain-Text Content Instance
Request
POST /onem2m/EXAMPLE_APP_NAME/EXAMPLE_CONTAINER_NAME/ HTTP/1.1
Host: localhost:8000
Content-Type: application/vnd.onem2m-res+json
{
"m2m:cin": {
"con": "EXAMPLE_VALUE",
"cnf": "text/plain:0"
}
}
Response
{
"m2m:cin": {
"ri":"cin1",
"ty":4,
"st":"0",
"cnf":"text/plain:0",
"lt":"2017-03-02T16:37:23.963247+00:00",
"et":"2017-03-02T17:10:43.963247+00:00",
"cs":13,
"pi":"cnt0",
"rn":"contentInstance-v2HDJeljran3jxPX",
"con":"EXAMPLE_VALUE",
"ct":"2017-03-02T16:37:23.963247+00:00"
}
}
Create a Base64-Encode Content Instance
For this subsection it is assumed that data represented as JSON will used to create a new content instance. Therefore, following example data:
{
"foo": 42, "bar": 42
}
needs to be trans-coded to its base64 string:
eyJmb28iOiA0MiwgImJhciI6IDQyfQo=
To be able to execute the trans-coding, be reminded of subsection Push base64 encoded data to a resource.
Request
POST /onem2m/EXAMPLE_APP_NAME/EXAMPLE_CONTAINER_NAME/ HTTP/1.1
Host: localhost:8000
Content-Type: application/vnd.onem2m-res+json
{
"m2m:cin": {
"con": "eyJmb28iOiA0MiwgImJhciI6IDQyfQo=",
"cnf": "application/json:1"
}
}
Response
{
"m2m:cin": {
"ri":"cin2",
"ty":4,
"st":"0",
"cnf":"application/json:1",
"lt":"2017-03-02T16:41:02.060806+00:00",
"et":"2017-03-02T17:14:22.060806+00:00",
"cs":32,
"pi":"cnt0",
"rn":"contentInstance-ccUmIDHZ2jvtUWyQ",
"con":"eyJmb28iOiA0MiwgImJhciI6IDQyfQo=",
"ct":"2017-03-02T16:41:02.060806+00:00"
}
}
Retrieve Latest Content Instances
Request
GET /onem2m/EXAMPLE_APP_NAME/EXAMPLE_CONTAINER_NAME/latest HTTP/1.1
Host: localhost:8000
Response
{
"m2m:cin": {
"ri":"cin2",
"ty":4,
"st":"0",
"cnf":"application/json:1",
"lt":"2017-03-02T16:41:02.060806+00:00",
"et":"2017-03-02T17:14:22.060806+00:00",
"cs":32,
"pi":"cnt0",
"rn":"contentInstance-ccUmIDHZ2jvtUWyQ",
"con":"eyJmb28iOiA0MiwgImJhciI6IDQyfQo=",
"ct":"2017-03-02T16:41:02.060806+00:00"
}
}
Reference: Short Resource names and Resource types
Resource names and types provides a reference of how names of resources are mapped to their short names but also provides a table that reveals the numerical representation of resource types.