Hypermedia Design for Machine Interfaces Part 2
Introduction and Background
The last article  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 . 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 . An online demonstrator for the Machine Hypermedia Toolkit can be found at .
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
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  (T2TRG).
- Define a collection based data model
- Define mappings to RFC 6690  and SenML  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 .
- 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  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.
Scripts that expose and consume resources, execute the "business logic" of things
Thing Description, Stateful Resources
REST, Pub-Sub: HTTP, CoAP, MQTT
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 ), 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.
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.
 Hypermedia Design for Machine Interfaces Part 1
 Machine Hypermedia Toolkit project
 Research Summaries from the Machine Hypermedia Toolkit project
 Online Demonstrator for Machine Hypermedia Toolkit
 RFC 6690
 W3C WoT Interest Group
 Working documents