Data models for the Internet of Things

Monday, April 3, 2017

Introduction

The most recent articles discussed some issues and design patterns for machine interaction using hypermedia controls, and presented an experimental open source software platform and demonstrator for an example machine-to-machine hypermedia system.

This article will summarize the progress on this topic over the last year and focus on the subject of asynchronous and realtime interactions using REST design principles and, in particular, hypermedia controls.

HSML: Hypermedia Content Formats for Machine Interaction

Since the last article, there is a new Internet Draft describing a content format for hypermedia collections on constrained networks. HSML is a simple representation and interaction model for collections and associated links, forms, and items, using CoRE Link-Format and SenML.

Reusable Content Format

HSML is an updated version of the content format described in the earlier articles, and is kept aligned with the current versions of SenML and CoRE Link-Format.

HSML representations include CoRE Link-Format and SenML, with some extensions to the Link-Format and SenML keyword vocabularies. In addition, there is a format which includes both Link-Format and SenML elements, to facilitate interactions with items and their link parameters in a collection atomically.

HSML provides for use of the Interface Type parameter (if) in links and request parameters, and is used to select representations of a resource as defined in CoRE Interfaces.

Common Transfer Layer

The HSML draft discusses a common abstract transfer layer using CRUD + Observe/Notify, also known as CRUD+N, which is used to map various concrete protocols, including HTTP, CoAP, and MQTT.

This supports a common model for resource state interaction, upon which a consistent hypermedia interaction model may be constructed, and from there be extended.

CRUD, REST, and Hypermedia

This discussion is based on REST system design in the context of distributed state machine design.

In REST system design, a distributed system is represented as a state transition graph. The nodes of the graphs represent states of the system, and the arcs of the graph represent possible state transitions.

The common resource design pattern known as CRUD exposes the system state contained in the nodes of the graph. Resource state may be Created, Retrieved, Updated, or Deleted.

Hypermedia controls expose the system state transition model at the edges of the graph. Hypermedia controls are the hyperlinks and submission forms, or their machine equivalents, that describe the available state transitions offered by the system, and how, from the client, they may be effected.

Hypermedia Controls Describe the Available State Transitions

To bring in another related set of concepts, hypermedia controls implement a set of "control plane" abstractions that work together with the "data plane" abstraction of CRUD, forming two aspects of a distributed system architecture.

Without hypermedia controls, CRUD clients and servers will generally need to be more tightly coupled. These systems tend to use early binding of clients to servers, with schemas and introspection, code generation, and related techniques to drive client state machines to consume resources.

With hypermedia controls to dynamically describe state transitions, REST clients can consume the hypermedia controls in order to understand how to drive system state transitions, in a more loosely coupled, separately evolvable, late binding way.

Hypermedia controls describe possible state transitions based on the current state of the system, rather than pre-determined by a static resource design.

Interactive and Reactive Hypermedia: Actions and Link Bindings

In the last article, a class of hypermedia controls was described that facilitates asynchronous and realtime interaction between hypermedia clients and REST servers. These belong to a general class of interactive, and reactive, Hypermedia controls, that can direct the transfer and processing of dynamically changing data and asynchronous events.

This article describes two types of this class of Interactive Hypermedia controls, Actions and Link Bindings, in more depth, with examples and terminology consistent with the HSML Internet Draft published in the IRTF Thing to Thing research group (T2TRG):

Problem statement and scope

Asynchronous interaction over REST involves use cases for asynchronous state transfer in both directions; from client to server, and from server to client.

In the client to server case, the problem is in describing incoming state transitions which may or may not have immediate results. This enables the client to interactively direct the server processing of actions through the REST model.

In the server to client case, the problem includes describing how to use asynchronous communication to communicate resource state changes outgoing, in real time, to clients in order to enable reactive client processing of server state changes and events.

A third case is when a server device is to be controlled by another device, which also exposes a server role. The problem in this case is how to describe the client role involved in state transfer between two or more server resources.

Actions and Forms

Incoming (from the client to the server) state transitions are state transitions that a client wishes to make on a resource, such as turning a power switch on or opening a garage door.

For incoming state transitions, the problem is how to inform the client what transitions are available and how to construct requests which change the resource state of the system in some way that may be more or less indirectly related to the control input. It is not always a simple and immediate CRUD state update. The state of the resource may need to be asynchronously monitored to complete the client state transition at some time in the future.

For example, an actuator may take some time to complete its action, like closing a motorized gate or garage door. The outcome may be uncertain, as in the case of power interruptions or mechanical blockage of the gate. These conditions result in a number of possible eventual outcomes which need to be returned to the client for processing and client state update.

A meta-model using the concept of an "action" is presented in the HSML draft. An Action describes and accepts a representation for a desired state change to a resource. The conceptual model is that the desired state change is "created" in the context of an Action resource, which then affects the state of the linked resource(s), and which can then be monitored for its eventual outcome.

An Action link is indicated by the value of "rel" including "action", and works in analogous fashion to a form in HTML; it describes what the action is expected to accomplish, like "turn on the light" or "add a post to the blog", and includes information on how to accomplish the action, like what method to use, which resource type, which content format, schema information to describe the payload, and descriptions of expected responses.

Action links can describe simple action operations that use REST state updates, or more complex actions which create representations of abstract action descriptions in collections of action instances. Such collections may be used to sequence submitted actions in FIFO or priority order, and for clients to track long running or pending actions which have not yet completed.

Actions may be performed directly on resources they are intended to update the state of, or they may be performed on proxy resources, as in the likely example of action instances crreated in a collection.

In the case that Actions are performed on a proxy resource, the resource may be indicated in the context of the affected resource(s) by including a link with the relation type including the value "alternate" and with a resource type indicating the type of action.

Link Bindings

For outgoing (from the server to the client) state transitions, there is the additional problem of describing how a client is expected to asynchronously obtain the state transitions as they occur, perhaps with some additional QoS parameters specified as system constraints.

The concept of a Link Binding is presented in the HSML draft. A link binding, in this context and in the context of the CoRE dynlink Internet Draft, is a hyperlnk that defines a dynamic data update from one resource to another.

The description of link bindings assumes that there is a generalized REST-hook mechanism in place for the source of resource state updates, which can be used to trigger the link binding transfer operation. CoAP Observe may be used if available, or HTTP EventSource, or MQTT Subscribe.

Link Binding

The link source and destination are generalized to allow resource state to be communicated using an extensible set of transfer protocols. For example, links using the "mqtt:" scheme will instruct the system to publish updates from the linked resource to an mqtt broker, or subscribe to an mqtt broker to obtain state updates for the linked resource.

The link binding can be located with the information source and cause information to be pushed or published to the destination resource, or it may be located with the destination resource and cause the source resource to be subscribed, observed, or polled.

Asynchronous Notification using the "monitor" relation

The link binding may be in fact stored and operated in a third place, separately from the source or destination, and mat use an agent at the third party to effect the source and destination transfer operations.

Link bindings may use different relation types to characterize transfer direction. In the examples above, the "monitor" relation type is used to describe a target resouce (monitor) which can be used to be informed of state changes in the context (monitored) resource. Another relation type is "boundto", as described in CoRE dynlink, which defines state transfer from the target resource to the context.

Link bindings may be defined with separate source and destination controls for transfer layer parameters like methods, content formats, and resource type queries. This enables link bindings to be generally used for resource state transfer, for triggering Actions, or for generating abstract events.

Link bindings may have different source and destination schemes, enabling link bindings to be used to convert protocols. For example, updates to a REST resource may be published to an MQTT broker using a link binding. Since the content format and other resource information can be obtained using HTTP, there is less need to augment the MQTT system with meta-data when used in this way.

For schemes that don't offer subscribe or observe, for example HTTP, RESThooks can be created and used in a structured way. Similarly, for systems using MQTT subscribe or CoAP Observe, link bindings enable the orchestration and inspection of dynamic resource interactions using graph techniques and tools.

Link bindings provide a means for conditional notification, using parameters to control the time period and value/change threshold for notification messages to be generated.

An extension to link bindings may be created which enables a link binding to consume a hypermedia action. This would enable cross-protocol adaptation without proxies, by using dynamic adaptation code in the libraries that consume the hypermedia controls.

System architecture examples

Interactive hypermedia controls enable the dynamic orchestration of client-server interactions by discovering actions and adding dynamic link bindings to connect resources, event sources, and event handlers. The following are some examples of system-level orchestration using interactive hypermedia.

Actions in hypermedia clients

The Action control enables a generic client to adapt to the state machine of the server when performing actuation and invoking actions. The client consumes the hypermedia control, using the information obtained to select an action, marshal its parameters, and apply the action to the resource using the correct method and content format.

Typically, the hypermedia control will be annotated with semantic identifiers to indicate the type(s) of action offered and the types of parameters expected, as well as any special response that may be returned.

Resouce servers may offer action design patterns optimized for the particular situation, and clients may adapt to a variety of patterns without a-priori knowledge, using hypermedia action controls.

Actions are indicated with a link relation "rel=action", as per the HSML draft.

In the examples below, a hypermedia application only needs to know the semantic meanings of the terms. The hypermedia client can adapt to the different server designs based on consuming the hypermedia action control.

Client wants the light to move to 77% brightness with a ramp time of 10 seconds

The resource at /example/light/moveto is an alternate resource for the collection at /example/light/brightness and offers action capability. The resource type (rt) is "moveto" which for action resources indicates the type of action.

Seeing the readable parameter interface on the brightness, the client could check the units and adapt if needed.

The broker could be a reachable service in the cloud, and the temperature sensor could be in a sleepy device behind a NAT firewall, or in a mobile phone.

In this example, the conditional notification parameters indicate that the representation of the resource will be published when the value changes by 1 unit or more from the most recent publication, will be published no more frequently than once every 10 seconds no matter what the change, and will be published at least once every 600 seconds even if no change occurs.

Device-to-device orchestration using link Bindings

Link bindings may be used to orchestrate asynchronous updates from one device to another.

For example, an on-off switch could be push updates to a controlled device upon changes of state.

Sunday, May 15, 2016

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).

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.

Friday, October 30, 2015

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.

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:

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.

<formaction="demo_form.asp"method="post">

First name: <inputtype="text"name="fname"><br>

Last name: <inputtype="text"name="lname"><br>

<inputtype="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:

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.

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.