The Intel® Context Sensing SDK REST API

This document will explain the different REST API commands supported by the Intel® Context Sensing SDK.

Prerequisites

Software

1. OS: Ubuntu* 14.04 or 16.04 or Windows® 10
2. Linux* terminal / Windows Command line
3. Curl*: Refer to Install Curl
4. Postman*: (optional third-party tool): https://www.getpostman.com/

Install Curl

We use curl to run the REST API commands, both on Linux and Windows.

You can download curl from: https://curl.haxx.se/dlwiz/. Alternatively, you can install Postman as a Chrome* browser extension and use that instead.

Generic Curl Options

Generic curl options are explained below for reference.

Start the Broker

1. Make sure you have the broker set up. For steps, see Setting up the Broker.
2. This section assumes you have Docker* already set up with Intel credentials. (Refer: Setting Up Docker)
3. Make sure you have a running instance of MongoDB*, which is required by the broker.

Start the Terminal

1. Start another terminal (or command line in Windows), separate from the terminal that the broker is running on.

Rest APIs

The code sections below illustrate terminal commands or JSON input/output.

Note:  This is an example of a command: command. Enter commands in a terminal window, and press Enter to run them. 

1. Get States
2. Get Item
3. Push States
4. Send Command

1. GetStates

GetStates returns the current state of the Bus, which is all the last known data for all endpoints and all types within that endpoint seen by the broker.

Actual Command Line

curl -v --noproxy '*' -X GET -H "Authorization: Bearer none" http://localhost:8888/context/v1/states

Result with Response Code : 200 OK

If everything goes well, you will get the following result on the terminal that runs the broker:

no authorization

If the broker database is empty, you will receive a JSON response on your REST API terminal, containing an empty list (example below). If you want to push some states and populate this data, see: Push States.

{
    "data": {
        "kind": "states",
        "items": []
    }
}

On the other hand, if you have any data populated, you will get a JSON response that has the last received/forwarded data of all the types of every endpoint. It will look something like the following:

{
  "data": {
    "kind": "states",
    "items": [
      {
        "value": {
          "datetime": "2017-09-21T23:56:40.948Z"
        },
        "dateTime": "2017-09-21T23:56:40.948Z",
        "type": "urn:x-intel:context:thing:ticktock",
        "owner": {
          "device": {
            "id": "08:00:27:a2:a9:32:sample_ticktock",
            "runtime": null,
            "name": null
          },
          "user": {
            "id": "5514838787b1784b6b6f9e9a",
            "name": null
          },
          "application": {
            "id": "2dcdg777z7uan4tbmbch3rvd",
            "name": null
          }
        }
      },      
      {
        "value": {
          "sent_on": 1509737046088,
          "motion_detected": false,
          "device_id": "RSPSensor8"
        },
        "type": "urn:x-intel:context:retailsensingplatform:motion",
        "dateTime": "2017-11-03T19:24:06.098Z",
        "owner": {
          "device": {
            "runtime": null,
            "* Connection #0 to host localhost left intact id": "0a:00:27:00:00:08:serviceMotionSensor",
            "name": null
          },
          "user": {
            "id": "5514838787b1784b6b6f9e9a",
            "name": null
          },
          "application": {
            "id": "2dcdg777z7uan4tbmbch3rvd",
            "name": null
          }
        }
      }
    ]
  }
}

2. GetItem

GetItem returns data from a specific Item over a period of time.

Actual Command line

curl -v --noproxy '*' -X GET -H "Authorization: Bearer none" http://localhost:8888/context/v1/items

Result with Response Code : 200 OK

If everything goes well, you will get a result on the terminal that runs the broker:

no authorization

On your Rest API Terminal, you will get a JSON response that contains the items:

{
    "data": {
        "kind": "items",
        "items": []
    }
}

3. PushStates

Allows you to push state/data to the broker. Make sure the state pushed complies with the registered JSON Schema.

In this example, we want to push the following:

{
  "states": [
    {
      "type": "urn:x-intel:context:type:media:audio",
      "activity": "urn:activity:listening",
      "value": {
        "type": "song",
        "title": "Very interesting Song",
        "description": "Song by Metallica on Garage Inc.",
        "genre": [ "metal" ],
        "language": "eng",
        "author": "Metallica"
      },
      "dateTime": "2013-04-29T16:01:00+00:00"
    }
  ],
  "owner": {
    "device": {
      "id": "c2f6a5c0-b0f0-11e2-9e96-0800200c9a66"
    }
  }
}

Actual Command Line

curl -v --noproxy '*' -X PUT -H "Authorization: Bearer none" -H "Content-Type: application/json" http://localhost:8888/context/v1/states -d '{ "states":[{"type":"urn:x-intel:context:type:media:audio","activity":"urn:activity:listening","value":{"type":"song","title":"Very interesting Song","description":"Song by Metallica on Garage Inc.","genre":["metal"],"language":"eng","author":"Metallica"},"dateTime":"2013-04-29T16:01:00+00:00"}],"owner":{"device":{"id":"c2f6a5c0-b0f0-11e2-9e96-0800200c9a66"}} }'

Result with Response Code : 204 No Content

If everything goes well, you will get a result 204 with no content:

On your terminal running the broker, you will get no content.

On your Rest API terminal, you will get no content.

4. SendCommand

SendCommand will send a command to be executed by the broker or pass it along to be executed by an endpoint and pass the endpoint's result back to the calling service.

An example transaction: Endpoint1 <--------> Broker <---------> Endpoint2 with function retrieveitem() called by URN, such as urn:x-intel:context:command:getitem

Actual Command Line

curl -v --noproxy '*' -X POST -H "Authorization: Bearer none" -H "Content-Type: application/json" http://localhost:8888/context/v1/command -d '{ "method": "urn:x-intel:context:command:getitem", "endpoint": { "macaddress": "0:0:0:0:0:0", "application": "sensing"}, "params": ["0:0:0:0:0:0:sensing", "urn:x-intel:context:type:devicediscovery"]}'

The -d option is used to send the JSON body. Refer to Generic Curl Options. The current body represents the following:

• "method": "urn:x-intel:context:command:getitem": is the URN exposing the function retrieveitem() from endpoint2.
• "endpoint": is the MAC address and application name of the service that needs to execute the method mentioned above (such as endpoint2).
  Note: A Broker can also serve as an endpoint with a MAC address: 0:0:0:0:0:0 and application name:sensing. One may also specify a different MAC address and application name for an endpoint2 in the system mentioned above.
• params: The arguments that are expected by the function in endpoint2, such as retrieveitem(). In the following example, we expect 2 arguments: 0:0:0:0:0:0:sensing and urn:x-intel:context:type:devicediscovery. This is function-specific.

Note:  You can send variations of this command by changing the endpoint, the URN for function(method) that endpoint supports, and the parameters the function is changing.

{
	"method": "urn:x-intel:context:command:getitem",
	"endpoint": {
		"macaddress": "0:0:0:0:0:0",
		"application": "sensing"
	},
	"params": [
		"0:0:0:0:0:0:sensing",
		"urn:x-intel:context:type:devicediscovery"
	]
}

Result with Response Code : 200 OK

If everything goes well, you will get a result on the terminal that runs the broker:

no authorization

On your Rest API terminal, you will get a JSON response that has a list of all devices registered and active with the broker.

{
  "result": {
    "body": {
      "type": "urn:x-intel:context:type:devicediscovery",
      "value": {
        "devices": [          
        ]
      }
    },
    "response_code": 200
  }
}

Setting up Docker*

If an install script was provided with this document, simply run it in the terminal: ./install_docker.sh

If not, below are steps that need to be completed to successfully install Docker:

1. Docker manual installation instructions: https://docs.docker.com/engine/installation/linux/ubuntu/#install-using-the-repository
2. Determine your host machine's DNS servers: nmcli dev show | grep 'IP4.DNS'
3. Set up daemon.json with the 'dns' key and your DNS addresses. Example: { "dns" : [ "10.0.0.2" , "8.8.8.8" ]
4. Add your user to the docker group: sudo groupadd docker sudo gpasswd -a ${USER} docker sudo service docker restart newgrp docker
5. Make sure you have access to hub.docker.intel.com by trying to log in in the web portal: https://hub.docker.intel.com
6. Associate Docker on your machine with your user account: docker login hub.docker.intel.com

Setting up the Broker

There are two options to set up the broker:

• Dockerized: Context repo from hub.docker.intel.com(preferred)
• Non-dockerized: context-broker-VERSION.tgz file

Notes

• This document only covers the preferred Dockerized method.
• The section assumes you have Docker already set up with Intel credentials. (Refer: Setting Up Docker)
• The broker requires a running instance of MongoDB.

1. Use Docker to pull the Mongo* image onto your machine.

docker pull mongo

2. Create a container named mymongodb and run it for the very first time.

docker run --name=mymongodb -d mongo

Note: For subsequent runs use: docker start mymongodb

3. Pull the Context Linux Broker image.

docker pull hub.docker.intel.com/context/context-broker:v0.10.5

4. Create a container named contextbroker and run it for the very first time.

docker run --name contextbroker -it -p 8888:8888 --link mymongodb -e MONGODB_HOST=mymongodb hub.docker.intel.com/context/context-broker:v0.10.5

Notes

1. For subsequent runs, use: docker start -i contextbroker
-i or -it is used to run in the foreground and to see the output in the current terminal.
2. To stop the context broker instance, use CTRL+C to interrupt when running in the foreground or docker stop contextbroker when running in the background.
3. In order to remove the container preventing the use of Docker start, use: docker rm –f contextbroker

If you have access to our GitHub* repository(Non dockeized)

1. Go into /broker

python3 runserver.py

If everything goes well, you will get a result on the terminal that runs the broker:

Listening of Http(s)
8888