Hypermedia Design for Machine Interfaces Part 2

Introduction and Background

The last article [1] described a hypermedia architecture and content format based on

Collections of resource items and hyperlink references to resource items
IETF CoRE link-format based hypermedia controls
Composite data representation using SenML

Since then, we have built a reference implementation of these ideas in the Machine Hypermedia Toolkit [2]. The primary goals were to create a reference implementation of the proposed content format and architecture from which to evaluate and further develop the core concepts including:

Hypermedia controls using RFC6690 and link extensions
Abstract transfer protocol mappable to HTTP, CoAP
Collection based resource model including links and data items
Content format mapping to REST interaction models
Link embedding and dynamic resource composition

The prototype implemented the proposed resource model, as well as a test framework consisting of rudimentary JSON-LD models, functions to construct resources from abstract semantic models, discovery of resources using resource model templates with semantic annotation, and abstract API binding to discovered resources.

In addition, a number of related research topics were explored and reports made to IRTF and W3C research groups [3]. An online demonstrator for the Machine Hypermedia Toolkit can be found at [4].

This was a very useful exercise and a number of valuable lessons were learned:

The structure of the base data model should be decoupled from the structures of the representation formats
A simple base model format should be maintained with a common namespace for link-params, link extensions, and data properties across different serializations
Asynchronous behavior should be designed into the request/response architecture using a consistent RESThook framework
Resource exposing scripts and callback handlers should have the same scripting interface as resource consuming scripts
A consistent model based interface for resource construction and discovery is useful and practical
It is necessary to expose some transfer layer information in order to bind interaction models to REST APIs; this is analogous to the idea of data in motion vs. data at rest

What next?

At this point the concepts are well developed and may be built out into a broader experimental framework. This is a summary of items for future development.

Define a content format appropriate for general machine hypermedia representation.

Some of the ideas need to be developed further into a concrete recommendation to enable broader exploration. These will be developed into a experimental draft for the IRTF Thing to Thing Research Group [5] (T2TRG).

Define a collection based data model
Define mappings to RFC 6690 [6] and SenML [7] representations
URI Processing rules, including query parameter processing
Define link embedding operations that enable dynamic composition of resource representations
Define a common set of hypermedia keywords based on current practices

Define abstract transfer layer operations that enable late binding to concrete transfer protocols like HTTP, CoAP, and MQTT

Enable resource handlers implementations of interaction models to understand data in motion in a protocol-agnostic way
Enable choice of protocol to be late binding based on content of a retrieved hyperlink

Develop a reference implementation of an abstract transfer layer and resource layer based on the specified content format and architecture [9].

Abstract transfer layer provides a protocol-neutral interface for APIs and device interfaces, Storage, and protocol bindings
Implement the W3C WoT Servient pattern using the transfer layer API for constructing and handling requests to exposed resources
Use the common resource and transfer layers to expose a scripting API
Scripts can construct resources to expose and discover resources to consume
Utilize W3C WoT Thing Description (TD) for resource models used in resource instance construction and discovery

W3C Web of Things

One goal is to create a reference implementation of the W3C Web of Things [8] architecture and the proposed JSON-LD based Thing Description language. The W3C WoT Architecture includes the concept of a Servient, which is a common interface for both consuming and exposing resources under control of an application or scripts. However, the W3C WoT group will not define specific transfer layers or resource layers.

Layer	Description
Application	Scripts that expose and consume resources, execute the "business logic" of things
Things	Thing Description, Stateful Resources
Transfer	REST, Pub-Sub: HTTP, CoAP, MQTT
Transport	UDP, TCP
Network	Ethernet, WiFi, 6LoWPAN, Thread

Thing Description resources use URIs and other transport specific identifiers to point to concrete resource instances. There is a need to define resource layers and mappings to transfer layers for WoT TD models to encapsulate. The W3C Servient pattern will be the architectural use case for the abstract transfer layer and common resource model. The resource model can be configured to expose a simple REST + Notifications API to expose WoT Event, Action, and Property resources with URI links.

Application scripts will construct and expose resources using Thing Description templates, with local callback handlers for resource access operations. The abstract transfer messages will be exposed to resource handlers in order to match hypermedia controls to the underlying interaction model.

Asynchronous Interaction Model

A simple RESThook based architecture can be used for subscribing to and receiving events from asynchronous data sources, including changes of measured properties and event sources. Using transfer layer patterns like CoAP Observe, MQTT Subscribe, and HTTP EventSource, the existing server transfer layer of request/response can be used to observe a resource for updates from other sources.

With this model, all interested clients register an OBSERVE or SUBSCRIBE request with the server. A hardware sensor driver or data source simply uses the UPDATE operation on the resource, and all observing clients will be sent a notification based on their registered requests.

The problem with this model is that there is a hidden element of client session state on the server that can't be discovered externally. While this can sometimes be thought of as a request in progress, there is some motivation to build a more explicit mechanism into the system.

Using a separate resource we call a link binding (mentioned in [1]), the Observation on a resource can be made explicit by the instance of the binding. Each binding results in one observer on the resource. The binding contains instructions for constructing a message that can update another resource or perform an action like publish a message to an MQTT broker. These may in turn be observed or handled by actuators, etc.

RESTful Actuation

For RESTful actuation, the actuation command will be mapped to the CREATE of a temporary resource in a collection of actuations. When the actuation is invoked, the handler will create a resource that will be periodically updated to reflect the progress of the running action. For brief actions, the only update my be to signal completion. For longer running actions, there may be incremental progress updates.

The client wishing to perform an action will construct a payload representing the desired action (perhaps based on instructions in a hypermedia form) and perform a CREATE operation on the actuation collection. The resource handler will return the location URI of the created resource, which the client may choose to observe and receive asynchronous notifications of the progress.