Page tree
Skip to end of metadata
Go to start of metadata

Overview

Resource Catalog provides a REST API to publish and discover devices and the resources they expose (e.g., temperature sensor, light switch).

The Resource Catalog API is described as a Swagger 2.0 specification and can be explored here.

The base URL of the API is configurable and defaults to /rc. Additional details and API use cases are documented below.

Use Cases

  1. Registering and updating Devices and Resources
    Main use case for Device Connectors, implemented via /rc/devices CRUD.

  2. Browsing the Resource Catalog entries
    Use case for applications and services, implemented using /devices and /resources

  3. Retrieving information about specific Devices and Resources
    Use case for client applications and services, implemented via /devices/<device-id> and /resources/<resource-id>

  4. Filtering Devices and Resources
    Use case for client applications and services, implemented via /devices/<op>/<path>/<value> and /resources/<op>/<path>/<value>


Protocols

Resources are sensors and actuators exposed by a Device. The distinction between them is implicit and follows from the Resource's protocol definition:

  • Read-only Resources are sensors: their state can be retrieved, but not modified (e.g., only GET method in REST protocol)
  • Write-only Resources are actuators: their state can be modified (e.g., only PUT method in REST protocol)
  • Both readable and writeable Resources act as both sensors and actuators: their state can be both retrieved and modified

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


MQTT

  • type: MQTT
  • endpoint: {"url": "scheme://address:port", "pub_topic": "/pub/topic", "sub_topic": "/sub/topic"}
    • url describes the broker connection information as a URL (RFC 3986) using the following URI scheme
    • sub_topic describes the topic on which the resource state updates are published
    • pub_topic describes the topic which is 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)


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)


TTL

Devices registered in the Resource Catalog can be provided a TTL (time to live) and if not updated within that TTL will expire: information about the Devices and all of their Resources will be removed from the Resource Catalog.
Devices with configured TTL have additional expires field that indicate the expiration timestamp.

Local Resource Catalogs that can be optionally exposed by Device Connectors and contain the devices and resources they expose to the outer world typically don't have TTL specified.


Pagination

The responses in /devices and /resources are paginated using the page and per_page parameters in the request URL.

The paginated results 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


Versioning

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

application/ld+json;version=1.0.0
  • No labels