Device Catalog API

Overview

Device Catalog provides a REST(ish) API to publish and discover devices and the resources they expose (e.g., Temperature sensor, Light switch).

Data Format

DeviceCatalog

The entry point of the Device Catalog API returns devices and their resources in the following format:

{
  "id": "/dc",
  "type": "DeviceCatalog",
  "@context": <string>,
  "devices": {},
  "resources":[],
  "page": <number>,
  "per_page": <number>,
  "total": <number>,
}

The fields id, type, and @context are used to enable LinkedData support and can be ignored by clients using the plain JSON API described in this document.

The resources array holds an array of Resources. The devices object holds a dictionary of Devices with ids as keys. page, per_page and total are used for pagination of the resources array.

Device

Each device is represented in the following format:

{
  "id": <string>,
  "type": "Device",
  "name": <string>,
  "description": <string>,
  "meta": {},
  "resources": [],
  "ttl": <number>,
  "created": <timestamp>,
  "updated": <timestamp>,
  "expires": <timestamp>,
  "page": <number>,
  "per_page": <number>,
  "total": <number>,
}

The field id needs to uniquely identify the device in the network and the convention is to construct it as the dgw-id/devicename.

The rest of the fields have following meanings:

• name is a short string describing a device (e.g., "DummyDevice")
• description is a human-readable description of a device (e.g., "Just a test of DGW")
• meta is any hashmap describing meta-information of a device
• resources is an array of Resources as described below
• ttl is an integer defining the Time-To-Live of a device registration
• created, updated, and expires are generated by the Device Catalog and describe TTL-related timestamps
• page, per_page and total are used for pagination

Resource

Each resource exposed by a Device has the following representation:

{
  "id": <string>,
  "type": "Resource",
  "name": <string>,
  "meta": {},
  "protocols": [
     {
        "type": <string>,
        "endpoint": {},
        "methods": [],
        "content-types": []
     }
  ],
  "representation": {}
  "device": <string>
 }

where:

• name is a short string describing a device (e.g., "TemperatureSensor01")
• meta is any hashmap describing meta-information of a resource
• protocols is an array of protocols which can be used to access and modify the resource state
  • type is a short string describing the protocol (e.g., "MQTT", "REST")
  • endpoint is an object describing the protocol endpoint (e.g., URL for a Web API)
  • methods is an array of protocol verbs (e.g., "GET,POST,PUT,DELETE" for REST, "PUB,SUB" for MQTT)
  • content-types is an array of strings representing MIME-types defined in representation
• representation is a dictionary describing the MIME-types supported by the resource
• device specifies the id of the device exposing this resource

Protocols

Resources can be exposed through different protocols, and below are conventions for describtion of some of such protocols (format of entries in the protocols array).

MQTT

• type: MQTT
• endpoint: { "url": "scheme://address:port", "topic": "/topic"}
• url describes the broker information (tcp/ssl, address, port) as a URL (RFC 3986)
• topic describes the topic on which the resource state updates are published (or topic which can be used to modify the resource state)
• methods: ["PUB", "SUB"] - array of supported MQTT messaging directions
• PUB - indicates that the resource state is published via MQTT
• SUB - indicates that the resource state can be changed via MQTT
• content-types: ["application/json", ...] - array of of supported MIME-types (RFC 2046). Empty means payload agnostic

See example

REST

• type: REST
• endpoint: { "url": "scheme://address:port"}
• url is the mandatory field describing the endpoint URL (RFC 3986)
• additional fields can be defined
• methods: ["GET", "PUT", "POST", ...] - array of supported HTTP methods (RFC 2616)
• content-types: ["application/json", ...] - array of of supported MIME-types (RFC 2046)

See example

Example

A registration describing a Device with a Dummy Sensor may look as follows:

{
   {
  "/dc/my-demo-gateway-1/DummyDevice": {
    "id": "/dc/my-demo-gateway-1/DummyDevice",
    "type": "Device",
    "name": "DummyDevice",
    "description": "Just a test of DGW",
    "meta": {
      "any": "key",
      "kind": "dummy"
    },
    "resources": [
      {
        "id": "/dc/my-demo-gateway-1/DummyDevice/RandomStream",
        "type": "Resource",
        "name": "RandomStream",
        "meta": {},
        "protocols": [
          {
            "type": "REST",
            "endpoint": {
              "url": "http://pi.homenetwork:9000/rest/DummyDevice/RandomStream"
            },
            "methods": [
              "GET"
            ],
            "content-types": [
              "text/plain"
            ]
          },
          {
            "type": "MQTT",
            "endpoint": {
              "url": "tcp://mqttbroker:1883",
              "topic": "/my-demo-gateway-1/DummyDevice/RandomStream"
            },
            "methods": [
              "PUB"
            ],
            "content-types": [
              "text/plain"
            ]
          }
        ],
        "representation": {
          "text/plain": {
            "type": "number"
          }
        },
        "device": "/dc/my-demo-gateway-1/DummyDevice"
      }
    ],
    "ttl": -1,
    "created": "2014-08-20T12:58:21.29182903+02:00",
    "updated": "2014-08-20T12:58:21.29182903+02:00",
    "expires": "0001-01-01T00:00:00Z"
  }
}

REST API

The REST(ish) API of the Device Catalog includes CRUD to create/retrieve/update/delete device registrations, a read-only API for (LinkedData-enabled) Resources they expose, and a simple filtering API to search through the catalog for both of them.

CRUD

• /dc returns all registered devices as DeviceCatalog
• methods: GET
• /dc/ endpoint for creating new entries in the catalog
• methods: POST
• /dc/<deviceid> returns a specific device registration given its id as a Device
• methods: GET (retrieve), PUT (update), DELETE (delete)
• <id> id of the registration
• /dc/<deviceid>/<resourceid> returns a specific resource of a specific registration given its id as a Resource
• methods: GET

Filtering

• /dc/<type>/<path>/<op>/<value>
• methods: GET
• <type> is either device/resource (returns a random matching entry in the corresponding format) or devices/resources (returns all matching entries as DeviceCatalog)
• <path> is a dot-separated path in the Device or Resource similar to json-path
• <op> is one of (equals, prefix, suffix, contains) string comparison operations
• <value> is the intended value/prefix/suffix/substring of the key identified by <path>

Example

curl http://catalog.example.com/dc/resource/name/equals/RandomStream

will return a collection of all devices in the catalog which have resources with name RandomStream (as the one described in the example above)

Pagination

The Resources returned in resources array in DeviceCatalog and Registration are paged using the page and per_page parameters.

The results are then include the following additional entries:

• page is the current page (if not specified - the first page is returned)
• per_page is the number of entries per page (if not specified - the maximum allowed is returned)
• total is the total number of Resources in the catalog

Example

curl http://catalog.example.com/dc?page=1&per_page=2 curl http://catalog.example.com/dc/my-demo-gateway-1/DummyDevice?page=1&per_page=2 curl http://catalog.example.com/dc/devices/name/equals/RandomStream?page=1&per_page=2

Versioning

API version is included as a parameter to the MIME type of request/response:

application/ld+json;version=0.1

Local/Remote catalogs

Local device catalogs are exposed by the Device Gateways and contain the devices and resources they expose to the outer world. The same registrations can also be published to remote catalogs (if configured).

Registrations in both local and remote catalogs have same ids, and for applications it is transparent with which catalog to work: both local and remote catalogs implement the same API.

Registrations in the remote catalog have a TTL and need to be updated before they are expired and removed. For devices in the local catalog, TTL = -1 ("never expires").