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 catalog API returns devices and their resources in the following format:

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

The id field is used throughout the API and describes the location (relative URL) of the returned resource, fulfilling the indentifiability REST interface constraint. For entry point, it equals to the path in the API endpoint URL, which is configurable and defaults to /dc.

The fields 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 id field is a relative URL providing a dereferenceable identifier of the device in the catalog. It is constructed as /path/ + device-id, where:

• path is the path in the catalog API endpoint URL
• device-id is a unique device identifier in the network and the convention is to construct it as 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 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>
 }

The id field is a relative URL providing a dereferenceable identifier of the resource in the catalog. It is constructed as /path/ + resource-id, where:

• path is the path in the catalog API endpoint URL
• resource-id is a unique resource identifier in the network and the convention is to construct it as dgw-id/devicename/resourcename

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 REST)
  • methods is an array of protocol verbs (e.g., "GET,POST,PUT,DELETE" for REST)
  • 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 (dereferenceable) id of the device exposing this resource

Protocols

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

MQTT

• type: MQTT
• endpoint: {"url": "scheme://address:port", "topic": "/topic"}
• url describes the broker connection information as a URL (RFC 3986) using the following URI scheme
• 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 describes 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 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 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.

As described above, the path is a configuration parameter setting the path in the catalog API endpoint URL.

CRUD

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

Filtering

• /path/<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 Device 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 entries 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 (but id fields are prefixed with the corresponding paths of the endpoints), 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").