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.