Data models for the Internet of Things : 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.

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.

First name: <input type="text" name="fname"><br>

Last name: <input type="text" name="lname"><br>

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