Sunday, May 15, 2016

Hypermedia Design for Machine Interfaces Part 2

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.

References

[1] Hypermedia Design for Machine Interfaces Part 1


[2] Machine Hypermedia Toolkit project


[3] Research Summaries from the Machine Hypermedia Toolkit project


[4] Online Demonstrator for Machine Hypermedia Toolkit


[5] T2TRG


[6] RFC 6690


[7] SenML


[8] W3C WoT Interest Group


[9] Working documents

Friday, October 30, 2015

Hypermedia Design for Machine Interfaces


From API Design to Hypermedia

This series of articles, “Data Models for IoT” started out, over three years ago, to explore the use of REST design principles for connected things. The design work followed a familiar pattern; since I don’t know yet how the hypermedia controls are going to work, I’ll instead start with mapping functional requirements to resource classes. To deal with the hypermedia controls, I’ll add a hypermedia metadata resource class that I can use to store semantic triples and I’ll figure out the discovery, state machines, and API automation later. Seems sensible, right?

The Smart Object API and IoT Toolkit reference implementation was developed based on this common design anti-pattern in REST APIs. As I started using these tools I found that the most powerful constructs were in using metadata to automate common operations like constructing resources and binding subscriptions to resources. However, I found myself building internal logic for things that I thought should really be using metadata. I spent a lot of code and time managing subresource relationships and figuring out whether there should be resources as named containers for other resources, and how should resources be named anyway? And somehow if I could just figure out how the hypermedia works things would be better. Sound familiar?

At the same time I began working on the IPSO Smart Object guidelines and OMA Lightweight M2M (LWM2M) standards to build application object models based on an object model consisting of a URI template and resource ID based semantic naming system. This additional set of constraints, described in an earlier article and numerous recent presentations, has proven to be very useful in avoiding having to answer the questions posed by the more open-ended resource model. The semantic definitions have also proven to be very useful, but the object model still requires a degree of foreknowledge built into the client about what the resource types are and how they behave. A lot of the benefit of the use of REST principles is being left on the table in these designs.

Most recently I am working with a new research activity in the IETF called the Thing to Thing Research Group (T2TRG). In this group we are looking at the fundamental design assumptions in REST and what that means for connected things and IoT. This is being done in collaboration with the new W3C Interest Group on Web of Things [WoT-IG]. The W3C group is looking at building information standards to enable web technology and design patterns to be used for interaction with connected things. Not surprisingly, the very same questions of hypermedia design are being considered in these groups.

So, I went back and read Roy Fielding’s dissertation again [Fielding2000], and carefully considered Roy’s more recent writing that specifically discusses hypermedia controls and calls for the use of Hypermedia As The Engine Of Application State (HATEOAS) [Fielding2008]. At the same time, I read a new book about API design from Mike Amundsen [WEBAPIS]. I began looking at how to annotate the existing “RESTful” APIs with hypermedia controls, and began to wonder what it means to really really design the hypermedia first? How can we apply this design principle of hypermedia first to machine interfaces? What does it mean?

What are the languages and design patterns for using HATEOAS to drive discovery of machine resources and operation of machine controls by applications? What is the equivalent of a web page, with it’s embedded hypermedia controls, when designed for a thing interface that’s meant to be consumed by a machine algorithm?

Hypermedia Design for Machine Interfaces

In this article, I will introduce some recent design insights based on trying to apply the principle of designing the hypermedia controls first. I start with a review of what is often ignored or deferred in REST API design, HATEOAS. Next is a review of how HATEOAS works in web pages with links and forms, and then a summary of a common design pattern called the collection.

Next I explore the design of collections for machine interfaces. In this design, the collection pattern is the basis for the organization of resources and resource metadata into the data structures that model the structure and affordances of the connected things they represent. The thesis in this article is that the collection pattern is, to machine resources and the web of things, what the HTML web page is to the web of browsers and servers. A design for a machine resource collection type is proposed and discussed.

Then we discuss interaction models, and how the Web of Things has a different interaction model requirement from the web of browsers and servers. The concepts of Properties, Events, and Actions are described as elements of the WoT Interaction model proposed by the W3C Web of Things Interest Group. Further, this model is mapped onto the collection design proposed in the previous section using hypermedia controls based on web links and forms.

Resource discovery is then discussed, with a focus on how the controls and affordances of a machine control API can be mapped to collections which allow the client application to incrementally reveal and discover resources required by the application. A high level design pattern using public resources like Schema.org is discussed.

Finally, a system example is presented which describes the use of the proposed hypermedia controls in a professional lighting use case, with some simple examples of lighting control and orchestration through the use of HATEOAS and web-like hypermedia controls

Hypermedia as used in WWW

REST, or Representational State Transfer, is the exchange of state information between an application and the resources consumed by the application. Resources are that part of the application state that is exposed and visible between components of the application, and shared between applications. Resources are usually hosted by a web server or cache, and the application is usually running in a web browser. In a Web of Things scenario, resources and applications may be hosted on connected devices or on servers, or on both.

Figure 1. The REST design pattern

Representations are state information which is encoded using a widely agreed-upon and well known content format or media type, and passed between the resource and application. The state of an application is updated by obtaining representations of resources from one or more servers. The state of resources are updated by representations which are transmitted from one or more applications to the resource. Resources often expose shared persistent state to many applications and application components.

Hypermedia As The Engine Of Application State, or HATEOAS, means that hypermedia is used to drive the interaction between applications and resources. Hypermedia is the descriptive metadata about how to exchange state information between applications and resources. Using hypermedia, applications can read the metadata and automatically consume resources. This results in a machine-understandable interface. Hypermedia defines REST [Fielding2008].

Hypermedia controls for HTML web pages consist of Links and Forms. Links and Forms are metadata which are embedded in resource representation of the web page, and are passed between the application and resource during interaction. Hypermedia links and forms drive the interaction model for HTML.

Links, also called Hyperlinks, describe how and where to obtain new state information which is related to the current state and context, and how to use it to update application state. Forms describe to the application how and where to transmit representations of new state information to the resource, and how to use the resource response to update the application state.

Links

Applications update their state by consuming links and resources pointed to by links and incorporating the state representations into the application state. The semantics of a hyperlink are “{The Current Context} has a {Relation Type} resource at {Target URI} which has {Target Attributes}” where Current Context is the URL that was fetched to obtain the link, Relation Type is link metadata that describes how the target resource is related to the current context, the Target URI is a pointer to the linked resource, and Target Attributes, also called link attributes, provide additional information about the target resource.

Here is an example hyperlink from RFC5988 Web Linking:

Link: <http://example.com/TheBook/chapter2>;rel="previous";title="previous chapter"

The above link indicates that the current context has a "previous" type resource at the URI “http://example.com/TheBook/chapter2” which has the “title” attribute value of “previous chapter”. The reader receiving this link may choose to update its state by selecting the link and going back to the previous chapter. Or not.

Here is an example hyperlink, in RFC6690 CoRE link-format:

<temperature>;rel="sub";rt="sensor";ct="application/senml+json";u="C"

Links may be represented in JSON, using the content-format application/link-format+json:

{"href":"temperature","rel":"sub","rt":"sensor","ct":"application/senml+json","u":"C"}

This link indicates that the URL currently pointed to and which returned this link has a “sub” type resource at the URI “temperature” which has the attributes “rt” (resource type) of “sensor”, “ct” (content format) of “application/senml+json”, and “u” (UOM) of “C” which is degrees Celsius.
The application may choose to update its state by caching the link, or reading or observing the temperature resource itself, or by ignoring the link.

Embedding Links are a special class of hyperlink which point to content that is to be considered part of the current context, or embedded in the current context. Example of embedding links are the image links in HTML pages, which result in the linked images being displayed in line with the content in the current context.

Forms

Applications update the state of resources according to the metadata instructions embedded in hypermedia forms. The semantics of a form are “To {Relation Type} {Current Context}, perform a {Request Description} to {Target URI}. The request description contains a method, such as PUT, POST, PATCH, DELETE, and a description of the expected representation to be applied to the target resource.

Here is an example of an embedded form in HTML.

<form action="demo_form.asp" method="post">
 First name: <input type="text" name="fname"><br>
 Last name: <input type="text" name="lname"><br>
 <input type="submit" value="Submit">
</form>

In HTML forms, “action” is the target URI and the input type indicates user input to the form. The example form says: “To submit input to the current context, POST a form containing “fname” and “lname” fields to the URI “demo_form.asp”.

Collections

Links and forms are used in a common hypermedia design pattern called a collection. A collection is a resource that has other resources, called items, associated with it. The associated resources may or may not be subresources of the collection resource. A collection has links which point to the items. Items are added to, edited, or removed from the collection using forms. adding an item to a collection adds a link to the item, and removing an item from a collection removes the associated link. Items may be discovered in a collection by examining the links.

For further information, the general collection design pattern is treated extensively in [WEBAPIS].

Collections for Machine Interfaces

To answer the question of the equivalent of web pages for machines, we need to look at the particular requirements that commonly emerge for machine APIs.

A modular resource structure is a common requirement, for a number of use cases:
  • Encapsulation of sets of reusable properties into an object or function block
  • Composition of these objects or function blocks into complex resource sets
  • Modeling complex things like appliances and machines using reusable elements
  • Discovery through incremental reveal using reusable semantics
  • Collective processing of resource sets and groups

There are many important use cases for collective processing of multiple resources, based on objects, function sets, or dynamically defined groups. In addition to dynamic resource groups, dynamic creation of resources is needed for bindings, subscriptions, and for long running executions like timers, actions, and scenes. Some APIs may want to enable dynamic creation of all resources.

Another question in the design of hypermedia for machine interfaces is how to expose the hypermedia controls to the application. In the case of HTML, the metadata are embedded in the text of the web page. Machine APIs typically will have separate content-formats for the links and for the item data. For example, the links may use RFC6690 CoRE Link-format [RFC6690], while the data items may use a json encoding like senml+json, or for simple values may use text/plain.

A hypermedia collection for machine interfaces would be structured to meet the above requirements. A design based on these requirements is described in [CoreInterfaces].

The main features of the hypermedia collection type are:

  • A hypermedia collection contains hyperlinks which point to and describe resource items in the collection. The items may be simple resources or may themselves be hypermedia collections, or resource items of any supported content format.

  • The items in the collection may or may not be subresources of the collection resource. If they are subresources of the collection resource then they may be processed within the context of the collection resource. An item may be a direct subresource of only one collection, but may be linked by any number of collections.

  • Multiple content-formats may be used to select different resource representations for the collection. There is at a minimum one content format for the links, there may be a content format for the items that supports embedding links, and there may be a content-format for the collection, which may represent both links and items.

  • A hypermedia collection may support embedding links for machine use cases. In general, embedding links provide for collective processing of requests across multiple resources in the collection.

  • A hypermedia collection may support query filtering, where query parameters are used to select zero or more links based on matching link relations and attributes.

  • A hypermedia collection may support dynamic creation of items. Links and items should be created and deleted together as atomic operations. Creation of items may use the collection content format in order to create link values along with items, and to avoid semantic conflicts with link embedding operations that POST to items.

Hyperlinks

Some examples of links in a hypermedia collection using application/link-format+json:

{"href":"/sen/","rt":"sensors"}  : Link to the /sen/ collection describing it as a resource type of “sensors”

{"href":"/sen/","rel":"grp"}  : Link to the /sen/ collection indicating that /sen/ is a member of a group in the collection in which the link appears.

{"href":"/sen/temp","rt":"temperature"}  : An absolute link to the resource at the path /sen/temp

{"href":"temp","rt":"temperature"}  : Link to the temp subresource of the collection in which this link appears.

{"href":"temp","anchor":"/sen/"}  : A link to the temp subresource of the collection at /sen/, which is selected by bulk operations that specify the resource name, e.g. {“href”:“temp”} (link-format+json) or {“n”:”temp”} (senml+json).

Items in the Collection

Items in the collection may be any supported content-format, but there is a content format based on JSON called SenML that is useful for representing both structured resources and time series data. SenML uses a simple data model to represent named items in a collection or subresources in a directory. An example structured resource representation in application/senml+json for a temperature sensor is:

{
"bn":"/sen/temp/1/",
"e":[
{"n":"currentValue","v":"31.3","u":"C"},
{"n":"maxValue","v":"37.1","u":"C"},
{"n":"minValue","v":"18.3","u":"C"},
{"n":"resetMaxMin"},
{"n":"minScale","v":"0","u":"C"},
{"n":"maxScale","v":"100","u":"C"},
{"n":"appType","sv":"Inboard Bearing"}
]
}

This represents a collection at base name “/sen/temp/” and its sub-resources with names “n”, values “v”, and UOM “u”. The individual subresources may be accessed using the base name and resource name, e.g. /sen/temp/currentValue which may return a text/plain representation “31.3”.

The Collection Content Format

For adding resource items to a collection, and for obtaining a full representation of both links and items in the collection, a third content format may be used. In this example we define a new content format of application/collection+senml+json. In the above example of the temperature collection, the collection representation may be constructed as follows, with an additional array labeled “l” containing the link-format+json representation of the links in the collection:

GET /sen/temp/1/ content-format=”application/collection+senml+json”

{
"bn":"/sen/temp/1/",
"e":[
{"n":"currentValue","v":"31.3","u":"C"},
{"n":"maxValue","v":"37.1","u":"C"},
{"n":"minValue","v":"18.3","u":"C"},
{"n":"resetMaxMin"},
{"n":"minScale","v":"0","u":"C"},
{"n":"maxScale","v":"100","u":"C"},
{"n":"appType","sv":"Inboard Bearing"}
],
"l":[
{"href":"","rel":"self","rt":"temperature","u":"C"},
{"href":"currentValue","rt":"currentValue","u":"C"},
{"href":"maxValue","rt":"maxValue","u":"C"},
{"href":"minValue","rt":"minValue","u":"C"},
{"href":"resetMaxMin","rt":"resetMaxMin"},
{"href":"minScale","rt":"minScale","u":"C"},
{"href":"maxScale","rt":"maxScale","u":"C"},
{"href":"appType","rt":"appType"}
]
}

Mapping of methods and content formats

Content formats and methods should be mapped to resource representations according to the following table:

Method
Content Format
Query
Embed Links
Result
GET
Links
Y
N
Return a representation of selected links
PUT
Links
N
N
Replace links with payload
POST
Links
N
N
Add links in the payload to the collection
PATCH
Links
Y
N
Modify or remove selected links
GET
Items
Y
Y
Return a representation of selected items
PUT
Items
Y
Y
PUT the payload to the selected items
POST
Items
Y
Y
POST the payload to the selected items
PATCH
Items
Y
Y
Apply the patch payload to selected items
DELETE
Items
Y
Y
Remove the selected items as an embedding link
GET
Collection
Y
Y
Return a representation with items and links
PUT
Collection
Y
Y
Replace selected items/links with payload
POST
Collection
N
N
Add items and links to the collection
DELETE
Collection
N
N
Remove the entire collection

Table 1. Mapping of Content Formats and Methods to the Hypermedia Collection

Embedding Links

Embedding link processing is an optional behavior implemented by a hypermedia collection. In embedded link processing, the URI of the collection is the target of the operation, and the content format is one which can support representation of resources, such as senml+json.

Read Items

For example, a GET of items in the collection returns all selected items in a single representation. Assuming the collection representing the temperature object above:

GET /sen/temp/1/ content-format="application/senml+json"

{
"e":[
{"n":"currentValue","v":"31.3","u":"C"},
{"n":"maxValue","v":"37.1","u":"C"},
{"n":"minValue","v":"18.3","u":"C"},
{"n":"resetMaxMin"},
{"n":"minScale","v":"0","u":"C"},
{"n":"maxScale","v":"100","u":"C"},
{"n":"appType","sv":"Inboard Bearing"}
]
}

Batch Update Items

The batch update sub-method of PUT, POST, or PATCH is invoked when resource names of items in the collection match resource names of item in the update payload. A batch update applies the corresponding value in the update payload to the resources in the collection that match the resource name in the update payload.

PUT /sen/temp/1/ content-format="application/senml+json"

{
"e":[
{"n":"minScale","v":"20","u":"C"},
{"n":"maxScale","v":"120","u":"C"},
{"n":"appType","sv":"Cold End Bearing"}
]
}

This would select items for update based on matching the resource names, resulting in the updated collection:

GET /sen/temp/1/ content-format="application/senml+json"

{
"e":[
{"n":"currentValue","v":"31.3","u":"C"},
{"n":"maxValue","v":"37.1","u":"C"},
{"n":"minValue","v":"18.3","u":"C"},
{"n":"resetMaxMin"},
{"n":"minScale","v":"20","u":"C"},
{"n":"maxScale","v":"120","u":"C"},
{"n":"appType","sv":"Cold End Bearing"}
]
}

If the content-format allows specification of link relations and attributes in the items content format payload, then batch updates may be selectively applied to resources according to matching link their relations and attributes with those specified in the update payload.

Group Update Items

The group update sub-method of PUT, POST, and PATCH applies the update payload to each item in the collection. Group processing of individual items in the collection may be indicated by using the new “grp” relation value in the link, i.e. <res1>;rel="grp". Link embedding operations which select this item will apply the entire update payload to the item.

In this example, a number of temperature sensors are grouped together and updated using a single operation. Given the group collection:

GET /sen/temp-group/ content-format="application/link-format+json"

[
{"href":"/sen/temp/1","rel":"grp","rt":"temperature","u":"C"},
{"href":"/sen/temp/2","rel":"grp","rt":"temperature","u":"C"},
{"href":"/sen/temp/3","rel":"grp","rt":"temperature","u":"C"},
{"href":"/sen/temp/4","rel":"grp","rt":"temperature","u":"C"}
]

An update of all of the resetMaxMin resources can be performed using a single operation:

POST /sen/temp-group/ content-format="application/senml+json"

[
{"n":"resetMaxMin":"v":null}
]

Query FIltering

Any item in the collection may be referenced by selecting a unique set of link attribute values in the query parameters, enabling a general capability to select and interact with resources by specifying their attribute values as an alternate addressing method instead of their URI (href value).

In the example above, query filtering may be used to return one or more properties from the collection.

GET /sen/temp/1/?rt=maxValue&rt=minValue content-format="application/senml+json"

[
{"n":"maxValue","v":"31.3","u":"C"},
{"n":"minValue","v":"31.3","u":"C"},
]

Query filtering should normally only be applied in the local context. It may additionally be useful to provide an explicit mechanism by which queries may be forwarded using group embedding links (rel=”grp”). One way is with a special query parameter “grp=fwd” that the collection resource will interpret as a query operation meant to be forwarded to the embedding link targets. For example, assuming the group collection above:

GET /sen/temp-group/?grp=fwd&rt=appType&rt=currentValue
content-format="application/senml+json"

would return the following payload:

[
{
"bn":"/sen/temp/1/",
"e":[
{"n":"appType","sv":"Cold End Bearing"},
{"n":"currentValue","v":"31.3","u":"C"}
]
},
{
"bn":"/sen/temp/2/",
"e":[
{"n":"appType","sv":"Hot End Bearing"},
{"n":"currentValue","v":"44.0","u":"C"}
]
},
{
"bn":"/sen/temp/3/",
"e":[
{"n":"appType","sv":"Ambient"},
{"n":"currentValue","v":"21.1","u":"C"}
]
},
{
"bn":"/sen/temp/4/",
"e":[
{"n":"appType","sv":"Frame"},
{"n":"currentValue","v":"33.2","u":"C"}
]
}
]

This implies that a senml text may consist of an object or an array of objects at it’s top level.

The WoT Interaction Model

In the first section, I mentioned that the interaction model for HTML forms is based on updating or adding content to a document, or selecting a link based on user input. This interaction model is appropriate for interactions involving information and documents, but a different interaction model is needed for hypermedia interfaces of connected things, to account for the dynamic, bidirectional, and and real-time nature of the expected interactions between things and between people and things.

The interaction model proposed by the W3C Web of Things (WoT) Interest Group [WoT-IG] is based on Properties, Events, and Actions. A thing according to the W3C model can be interacted with through these abstractions of properties, events, and actions.

Properties are data values that define the state of the thing and it’s configuration and settings. Properties include data like manufacturer name and model number, as well as representing the current values of sensor inputs or control settings. Properties may be read-only or they may be readable and writeable. Properties may also be able to be observed or subscribed to for notifications of changes in state.

Events are state changes in properties and other phenomena that the thing is able to report or send asynchronous notifications of. There is a list of potential events for each thing or sub-thing, and these events may be subscribed to. In addition, there may be one or more notifications in progress of events that have occurred.

Actions are state changes the application invokes on a thing. In this sense they are most like forms, but for invocation of actions. An application wishing to invoke a state change on a thing may use a hypermedia control like a form to invoke the action.

Mapping the WoT Interaction Model onto Collections

In mapping the WoT interaction model to hypermedia controls, there are a few simplifying assumptions. First is that there are properties that represent the entire observable state of the thing. This includes the parameters for actions that can be invoked and events that can occur. If there is some state information that is communicated in an event or action, there should be one or more corresponding properties that can be said to represent the state or state update. For example, a log message may be mapped to a property that is created or updated when the message is sent.

Thus only property resources, or properties, are mapped to concrete resources that may change state, and these properties may emit or consume event and action information. Events and actions themselves are hypermedia controls that map to specific properties as data streams and control parameters.

Thus the discoverable “events” associated with a thing are hypermedia controls that instruct an application how to create subscription resources to observe sets of properties. When an event occurs according to some current subscription, a notification may be created.  Notifications correspond with asynchronous network messages or internal messages that are sent to update other resources or to invoke handlers in application software.

Likewise, a thing’s discoverable actions are hypermedia controls that inform applications how to create action resources, which use property resources as function input parameters and state triggers in order to invoke particular actions. For example, an application may discover a level control action for dimming a light. This is a hypermedia control that instructs the application how to construct the control parameters using properties of the light, and how to invoke the light dimming action.

Properties

Properties of a thing may be represented as items in one or more collections. Properties which are related to one another and which are processed in the same context may be members of the same collection. For example, there may be a small collection of properties that represent the state of a push button. The current state may be one property, another may represent the number of times the button was pushed, and another for how long the button has been held down. The collection may represent the button, and the different properties may represent different accountings of the button’s state. A brightness control function block for a light may have one property to represent the current brightness and other properties that represent the future brightness level and transition time settings. Another property may indicate the remaining time for a previous brightness change to complete.

Figure 2. A collection of Properties (schematic)

Events

Events are based on state changes of properties. This enables events to be based on conditional filtering of the property values, or for the properties to contain arbitrary messages generated by internal state changes. An event exposed by a thing consists of a hypermedia control that informs applications how to create a subscription to the property or properties that define the event and how to invoke the associated condition. The subscription is a resource created by the application which configures the event filtering condition and the associated notification configuration. When the event condition of a subscription is met, a notification may be generated that creates a message containing the notification and also creates a resource that represents the notification.

The event controls may be stored as links and form metadata in a collection semantically labeled as the thing’s events. The links in the collection may have their own semantic descriptors that describe the semantics of the event. This enables discovery by incremental reveal. Subscriptions may be created as items in a subscriptions collection for the thing, enabling discovery and management of subscriptions by applications. When notifications are generated they may also be created as items in a notifications collection. This may be structured as a collection for each subscription resource or as a notifications collection for the entire thing.


Figure 3. Hypermedia Events

Actions

The Actions exposed by a thing are hypermedia controls that specify property values to be used as input parameters to the action and how to invoke the action. To invoke an action on a thing, an application uses the hypermedia controls to assemble the input parameters and create a new actuation resource on a collection of scheduled actuations. The actuation resource may be used by the application to track and manage the execution of long-running actions. There may be a collection of notifications associated with actions that the application may use to synchronize to the life cycle of the actuations.


Figure 4. Hypermedia Actions

Discovery - Catalogs and Links

In the context of this article, discovery refers to the identification of resources of interest by semantic classification of link attribute values. That is, resources are “discovered” by applications by matching link attributes of the resources with link attribute specifications presented by the application. The link attribute values are assumed to be semantically significant to classify resources of interest.

Well Known Namespace

For example, a resource may be marked with a link attribute rt=”temperature” as in the above example. The term “temperature” is assumed to be derived from a well known namespace with a well defined semantic meaning. In this example, “temperature” is in the UCUM namespace, the Unified Codes for Units of Measure.

If an application like a room control thermostat needs to identify or discover sources of temperature information, it can use the well known term to search for the link attribute rt=“temperature” in collections of links that might contain temperature type resources. It can further determine from other metadata which are the best sources of temperature data if multiple potential sources are found.

Schema.org

The web today uses this concept to enable applications to identify hypermedia controls and resources in web pages, based on a public resource hosted at schema.org. The schema.org resource contains definitions for many common entities used in web interactions involving people, products, and services. Some examples are Events, such as sporting events, and Products, with descriptions of common attributes and terms. The range and domain of a particular entity is described, what it can contain and what entities it can relate back to, for example in schema.org an attendee of an event may be a person or it may be an organization.

Schema.org is a community build metadata set that was created by a set of web providers like Google and Amazon in order to have a common vocabulary and ontology for common web interactions. In the same way, a community resource may be built by domain experts and service providers to describe and classify connected products and their affordances and methods. For example, it could be based on a taxonomy of Properties, Events, and Actions based on the W3C WoT Interaction Model.

Resource Annotation using Link Attributes

Resources in a connected product may then be exposed in collections by adding link attribute values that are drawn from the public vocabulary and ontology. For example, if there is a vocabulary for lighting controls, then there may be a set of brightness control actions and a set of color control actions, referred back to standard measures for brightness and color. A connected lighting product may annotate the links in the collections it exposes using these terms.

Applications wishing to interact with the connected things might first use a search an index or catalog containing relevant terms to discover the network addresses of potential devices, then would use a well known entry point, analogous to index.html for web pages, to query links on the devices for link attributes describing the specific resource types of interest.

Attribute Based Discovery - Resource Directories and Indices

Links on a device may be structured in collections with links to collections perhaps linking to other collections and so on. In this way, discovery may use gradual reveal of attributes from the starting discovery address to the resources of interest. Additional collections of links may be created to serve as search indices to enable discovery of popular resources using fewer link fetch operations. Clients may cache links and attributes to enable direct access of linked resources once the links are consumed the first time.

To facilitate network discovery of resources, links may be registered in catalogs [Hypercat] and resource directories [CoreRD] that are external to the device. These links may be full descriptions of all resources, or they may be index structured link collections that provide shortcuts to resources of expected interest, for example the on/off control of lights to enable easy grouping of controls in a room.

DIscovery of link attributes may use query filtering to search in collections for links having particular attributes. For example, an application wishing to identify temperature data may perform a GET to an index collection using the query parameter ?rt=temperature to only select links and items that contain the link attribute rt=”temperature”.

The resource type attribute, rt, can be used more than once in a link, making it possible to use multiple attributes to describe a particular resource. For example, a lighting control resource may have the link attributes:

</light/actions/level/change>;rt=”action”;rt=”brightness”;rt=”change”

to describe an action control that is used to change the brightness of an example light.

These terms would be drawn from some public vocabulary like schema.org and would also be used by a client in submitting in a query on an index collection, for example:

GET /index/?rt=action%3Abrightness%3Achange content-format=link-format

if applied to a collection containing the above link, would return the link:

200 OK
</light/level/actions/change>;rt=”action”;rt=”brightness”;rt=”change”

A scripting interface could select terms from the public namespace and fill out a template for discovery, submitting the template to a wrapper around the collection query and link pattern to start at a discovery entry point and follow links until the resource URI is resolved. This is known as the “follow your nose” pattern in discovery.

System example for a demonstration and learning prototype

Professional Lighting Control Model

To illustrate these concepts and to learn more about hypermedia controls for machine interfaces, a concrete example is developed based on a control model for connected lighting. A connected light using this model may implement one or more of the control options depicted below:

Figure X Control Model for Lighting

In addition, there may be sets of links and properties that describe the light and expose device management features and affordances. Likewise there may be events supported by the light or by embedded switches and sensors that are integrated with the light.

The prototype uses collections of links, properties, and hypermedia controls to implement a version of the WoT Interaction model for an example connected lighting product. Collections are used to structure resources and provide interaction through hyperlinks.

The concepts of incremental reveal and modular structure enable the application to incrementally discover resources based on their semantic types as described in the public repository, in this example “schema.connectiot.org”. This is analogous to the way schema.org is used for www resource descriptions.

This example will describe some of the resource structures using hypermedia collections. First, the application starts from a well-known location on the device, like .well-known/core as recommended in [RFC6690]. In this example. we assume that resource discovery starts at “/”.

The content formats that resources support tells the client what kind of resource they are. Resources supporting link and collection formats are collections, and resources that support only item formats are properties.

The following content format mapping to binary ID is used in the example:

22001
application/collection+senml+json
22002
application/senml+json
22003
application/link-format+json
22004
application/forms+link-format+json

Example HATEOAS requests and responses from discovery to actuation

The root resource is a collection that points to the highest level of resource organization:

GET / content-format=22003

[
{"href":"http://schema.connectiot.org/wot-things/","rel":"describedBy"},
{"href":null,"rel":"self","rt":"thing"},
{"href":"light/","rt":["thing","lampe"],"ct":[22001,22002,22003]},
{"href":"switch/","rt":["thing","control"],"ct":[22001,22002,22003]},
{"href":"pres/","rt":["thing","presence"],"ct":[22001,22002,22003]},
{"href":"dm/","rt":["thing","management"],"ct":22003}
]

Here we find the first 2 links describe the root context, first a reference to the namespace that the semantic terms are drawn from, then the link describing itself as a thing.

The next 4 links point to subresources of the root collection that represent the various affordances of the thing. It contains a thing which is a lampe, a thing which is a control, a presence thing, and a management thing.

We know that we are looking for resources that have brightness controls and we know, based on our reading of schema.connectiot.org/wot-thing, that a lampe is likely to have a brightness control as one of its actions.

GET /light/ content-format=22003

[
{"href":null,"rel":"self","rt":["thing","lampe"]},
{"href":"level/","rt":["thing","brightness"],"ct":[22001,22002,22003]},
{"href":"onOff/","rt":["thing","onoff"],"ct":[22001,22002,22003]}
]

Based on the returned link attributes resource type, we find a brightness type resource at the URI “level” in the collection at “/light/’. So fetching this resource

GET /light/level/ content-format=22003

[
{"href":null,"rel":"self","rt":["thing","level"]},
{"href":"properties/","rt":"properties","ct":[22001,22002,22003]},
{"href":"actions/","rt":"actions","ct":[22004]},
{"href":"events/","rt":"events","ct":[22004]},
]

I know also from reading schema.connectiot.org that I would find the action I’m looking for in the  actions type resource, which is a collection of forms that inform how to perform certain actions.

GET /light/level/actions content-format=22004

[
{"href":null,"rel":"self","rt":"actions"},

{"href":"../actuations","rel":"action","rt":"change","method":"post",
"ct":22001,"params":[{"name":"targetValue","range":"0-100"},
                     {"name":"transitionTime"},"units":"s"],
           "template":{"e":[{"n":"change","v":"$targetValue"},
                       {"n":"ttime","v":"$transitionTime"}]}
},
{"href":"../actuations","rel":"action","rt":"step","method":"post",
"ct":22001,"params":[{"name":"stepSize","range":"0-100"},
                     {"name":"transitionTime"},"units":"s"],
           "template":{"e":[{"n":"step","v":"$stepSize"},
                       {"n":"ttime","v":"$transitionTime"}]}
},
{"href":"../actuations","rel":"action","rt":"move","method":"post",
"ct":22001,"params":[{"name":"rate","uits":"%/s"}],
           "template":{"e":[{"n":"move","v":"$rate"}]}
}
]

I know, also from vocab.connectiot.org, that I want to “change” the brightness. Since this is one of the actions, I will use that form to invoke the change action on the brightness resource.

Discovery Optimization

By making use of query filtering based on expected resource types derived from type names at schema.connectiot.org, the returned payloads could be much shorter:

GET /light/?rt=brightness content-format=22003

[{"href":"level/","rt":["thing","brightness"],"ct":[22001,22002,22003]}]

GET /light/level/?rt=actions content-format=22003

[{"href":"actions/","rt":"actions","ct":[22004]}]

GET /light/level/actions/?rt=change content-format=22004

[{"href":"../actuations","rel":"action","rt":"change","method":"post",
"ct":22001,"params":[{"name":"targetValue","range":"0-100"},
                     {"name":"transitionTime"},"units":"s"],
           "template":"{"e":[{"n":"change","v":"$targetValue"},
                            {"n":"ttime","v":"$transitionTime"}]}"
}]

Having obtained this form, the application constructs and submits the following action request to change the brightness to 50% over a period of 10 seconds:

POST /light/level/actuations content-format=22001

{"e":[{"n":"change","v":"50"},{"n":"ttime","v":"10"}]}

201 Created Location:/light/level/actuations/19934577

This response indicates success, and passes back the location of the actuation object that was created to represent the actuation command. The actuation may be managed while in progress by interacting with the actuation resource. For example, performing:

DELETE /light/level/actuations/19934577

Cancels the actuation in progress and removes the actuation resource from the collection.

Event Subscriptions

Applications use a similar forms-driven method to subscribe to events and receive event notifications. The collection of event forms contains descriptive resource type identifiers which enable applications to select event types from the public vocabulary, configure the event conditions for notification, and receive notifications.

Summary

The hypermedia controls described in this article are based on adapting common web design patterns for use in machine APIs. The hypermedia collection type is described further in [CoreInterfaces]. The Web of Things Interaction model is described in [WoT-IG].

The design of appropriate hypermedia controls and resource structure for machine interfaces is the subject of further investigation and research.

The next step is to build a prototype reference implementation of the Hypermedia Collection class and Property class, and implement an end-to-end control application using the lighting use case.

A reference HATEOAS client will discover and interact with machine resources using only knowledge of a few content formats and the hypermedia controls provided by the device.

References

[WEBAPIS] Richardson, L. and M. Amundsen, "RESTful Web APIs”, O'Reilly, September 2013