chain-api-example.md

Chain API is a server that your devices can interact with using HTTP POSTs and HTTP GETs for finding and managing a hierarchy of Sites>Devices>Sensors. After a device has been described to the Chain API server, that Device can then send its data via HTTP POST to the CHAIN API server. The Chain API server then publishes URIs so that other Devices can HTTP GET the historical data of a Device's Sensor(s) as well as a WebSockets URI for each Sensor for subscribing to a live feed of the data as it comes in.

Example

To explain how to accomplish the said purpose of Chain API, I'll interact with a Chain API server using curl from the command line to carry out the following tasks.

1. Create a Site on a Chain API Server
2. Create a Device at that Site
3. Create a Sensor at that Device
4. Post data to that Sensor
5. Get historical data for our Sensor

1 - Create a Site on a Chain API Server

Find the Sites listings.

curl -XGET http://chain-api.media.mit.edu/ 

{
  "_links": {
    "curies": [{
      "href": "http://chain-api.media.mit.edu/rels/{rel}",
      "name": "ch",
      "templated": true
    }],
    "self": {
      "href": "http://chain-api.media.mit.edu/"
    },
    "ch:sites": {
      "href": "http://chain-api.media.mit.edu/sites/",
      "title": "Sites"
    }
  }
}

We found URI to ask for sites in Object._links["ch:sites"].href. Ask for all Sites listings.

curl -XGET http://chain-api.media.mit.edu/sites/

{
  "totalCount": 7,
  "_links": {
    "curies": [{
      "href": "http://chain-api.media.mit.edu/rels/{rel}",
      "name": "ch",
      "templated": true
    }],
    "self": {
      "href": "http://chain-api.media.mit.edu/sites/?"
    },
    "createForm": {
      "href": "http://chain-api.media.mit.edu/sites/create",
      "title": "Create Site"
    },
    "items": [{
      "href": "http://chain-api.media.mit.edu/sites/1",
      "title": "Tidmarsh Testing Install"
    }, {
      "href": "http://chain-api.media.mit.edu/sites/2",
      "title": "API Demo Dummy Site"
    }, {
      "href": "http://chain-api.media.mit.edu/sites/4",
      "title": "Tidmarsh Test 2"
    }, {
      "href": "http://chain-api.media.mit.edu/sites/6",
      "title": "Abu Dhabi PreTest"
    }, {
      "href": "http://chain-api.media.mit.edu/sites/7",
      "title": "Tidmarsh"
    }, {
      "href": "http://chain-api.media.mit.edu/sites/5",
      "title": "MIT Media Lab"
    }, {
      "href": "http://chain-api.media.mit.edu/sites/8",
      "title": "Server Metrics"
    }]
  }
}

2- Create a Device at that Site

In Object.createForm.href we found the URI that we can HTTP POST to for creating a Site as well as HTTP GET for getting the format that HTTP POST should be. Let's first HTTP GET the format of the Site we'll later HTTP POST.

curl -XGET http://chain-api.media.mit.edu/sites/create

{
  "required": ["name"],
  "type": "object",
  "properties": {
    "geoLocation": {
      "required": ["latitude", "longitude"],
      "type": "object",
      "properties": {
        "latitude": {
          "type": "number",
          "title": "latitude"
        },
        "elevation": {
          "type": "number",
          "title": "elevation"
        },
        "longitude": {
          "type": "number",
          "title": "longitude"
        }
      },
      "title": "geoLocation"
    },
    "name": {
      "minLength": 1,
      "type": "string",
      "title": "name"
    },
    "rawZMQStream": {
      "title": "rawZMQStream",
      "type": "string",
      "format": "uri"
    }
  },
  "title": "Create Site"
}

We'll now take the response from that HTTP GET, edit some of the fields for our own Site, and send that edited object using an HTTP POST to create our own Site.

CURL -XPOST -H "Content-Type: application/json" http://chain-api.media.mit.edu/sites/create -d "..."