Hypermedia Design for

Machine APIs

Web Scale Architecture for the Web of ThingsMichael J Koster

14 September 2015

Fielding 4.3 [Fielding2000] • Hypothesis I: The design rationale behind the WWW architecture

can be described by an architectural style consisting of the set of constraints applied to the elements within the Web architecture.

• Hypothesis II: Constraints can be added to the WWW architectural style to derive a new hybrid style that better reflects the desired properties of a modern Web architecture.

• Hypothesis III: Proposals to modify the Web architecture can be compared to the updated WWW architectural style and analyzed for conflicts prior to deployment.

What is REST?• Exchange of state information

between applications and resources

• Resource State is part of the application state

• State is exchanged through representations of the resource

• Application state is updated by application obtaining a current representation of the resource

• Resource state is updated by application transmitting a new representation of the resource

Application

Resource

Representations of State Information

What is HATEOAS?• Hypermedia As The Engine Of Application State• Hypermedia is the descriptive metadata about

how to exchange state information between applications and resources

• An application can read the hypermedia and automatically consume resources

• Such an interface is machine-understandable• Hypermedia defines REST [Fielding 2008]

Hypermedia Controls for HTML

• Links and Forms embedded in the resource representations of web pages constitute a hypermedia interaction model for HTML

• Links describe how and where to obtain a resource state representation and how to use it to update application state

• Forms describe how and where to transmit a representation of the resource to update the resource state

How Links Work• Applications update their state by consuming

resources indicated by links and incorporating the resource state into the application state

• The semantics of a link are “{Current Context} has a {Relation Type} Resource at {Target URI} which has {Target Attributes}” [Hartke2015]

• Relation Type indicates how the Target Resource is related to the Current Context

• Target Attributes may include media type

Embedding Links

• There are outbound links, described above, and embedding links

• Embedding links enable the embedding of resources within the Current Context

• Examples are <img> and <script> tags in HTML• Linked embedded resources are processed as

part of the Current Context

How Forms Work• Applications update the state of resources by

submitting representations according to the meta data instructions provided by the form

• The semantics of a form are “To {Relation Type} {Current Context}, perform a {Request Description} to {Target URI} [Hartke2015]

• Relation Type indicates the desired action on the Current Context, e.g. Add an article to a blog

• A form can also be used with GET to create a typed outbound link according to a URL template

The Collection Pattern• Very common design pattern [WEBAPIS] • Good example of the use of HATEOAS • Collection is a resource that contains links to resources, which

are items in the collection• Application uses links to list items and obtain links to resources in

the collection• Application uses forms to add items to, or remove items from the

collection• Adding an item to the collection adds a link to a resource to the

collection• Removing an item from the collection removes the link to the

resource from the collection

Hypermedia Languages• HTML – Links and Forms embedded in web pages• Microdata – Schema.org; RDFa metadata

embedded in web pages• CoRE Link Format (RFC 6690)• JSON-LD – WoT Thing Description Language• (Many others)• How is the hypermedia control exposed in the API? • How does it drive application state?

Thing Description Language

• What are Events, Actions, and Properties?– Elements of the WoT Interaction Model– Resource Classes with hypermedia controls

• Re-use the semantics of HTML Links and Forms but for machine interactions

• HATEOAS for machine APIs

The Action Pattern• Used to invoke Actions on a target resource• Parameters are controls on the execution of the action• The Action is invoked with a binding to a particular set of

parameters• Parameters may be mapped to defined resources or properties• Invoking an action creates a reference to a representation of a new

instance of the action scheduled to be executed on the target resource

• Action instances are reference-able entities that may be used to modify or cancel the execution of an action which is currently executing or pending execution

• Actions may be removed from the system after the completion of execution of the action has been handled

• Actions may use the collection pattern

The Event Pattern - Subscriptions• Events are emitted from a target resource to transmit

state information asynchronously• An event may contain a representation of resource

state• A resource has associated with it a collection of event

types it can emit• The Subscription pattern is used to associate a

particular event type and condition set with the invocation of a protocol handler

• Each event type may have an associated collection of Subscription resources

The Event Pattern – Notifications• Each event occurrence creates a new resource, which is

added to a collection of event occurrences for each Subscription

• Each event occurrence may have associated with it a notification

• A notification is a protocol handler which sends an event message to a target resource or handler location defined by a URL

• Sending of event messages may be abstracted by hypermedia controls embedded in the Subscription resource

HATEOAS Design for the WoT Interaction ModelResource

Class Hypermedia Controls

Actions - Form-like constructs use POST to execute actions based on parameters mapped to resources

- POST creates a new Action resource and schedules the action for execution

- Action resources are used to track and control ongoing execution of actions

Events - Form-like constructs use POST to create and subscribe to Events

- Events use the Subscription Resource pattern - Events and Subscriptions are managed in collections

Properties - Links and attributes provide a simple hypermedia control for getting and setting property values using GET and PUT

- Properties may be of any media type

Hypermedia Controls for Machine APIs

• Some common attributes and semantic features could be useful for machine APIs

• Describe media types in Actions and Events• Add parameters to Actions and Events• Describe Data Types and Data Templates• Provide for additional methods, PUT, PATCH• Provide a way to process response codes and

response metadata from the resource

Lighting Domain Example• Professional lighting controls based on a popular

control model• Actions for on-off control, dimming, and color

control for various colorspaces are encapsulated in optional capability modules

• Various control modes are optionally supported: Change, Step, Move, Toggle

• Control abstractions allow for controllable timed and smooth transitions between resource states

Control Model for Lighting

light

onOff

level

color

change

toggle

newState:{enum:off,on}

HS

XYtemperature

change

step

move

targetValue:{units:%}

transitionTimerate:{units:%/s}

stepSize

stop

transitionTime:{units:s}

changestep

move

targetValue:{units:K, range:2700-5500}

transitionTime

rate:{units:K/s}

stepSizetransitionTime:{units:s}

stop

light.onOff.change{newState:on}

light.color.temperature.change {targetValue:3400,transitionTime:10}

light.level.change {targetValue:45,transitionTime:10}

thing actuators actions parameters application actions {parameters}

(colorspace)

Example Hypertext Links to Propertieshypertext links at resource context = /light

[{“rel”: “property”,“href”: “ColorTemp/currentValue”,“type”: “observable”,“name”: “ColorTemperature”},{“rel”: “property”,“href”: “ColorTemp/remTime”,“type”: “observable”,“name”: “TransitionTimeRemaining”}]

/light has observable property resources:“ColorTemperature” at the URI /light/ColorTemp/currentValue“TransitionTimeRemaining” at the URI /light/ColorTemp/remTime

Hypertext Link to Actuator

hypertext link at resource context = /light

{“rel”: “action”,“href”: “ColorTemp”,“type”: “actuator”,“name”: “ColorTemperature”}

“/light has an actuator type action resource named ColorTemperature at the URI /light/ColorTemp”

Hypertext Form for Change Action hypertext form at resource context = /light/ColorTemp: { “rel”: “action”, “type”: “action”, “name”: “Change”, “method”: “POST”, “href”: “Actions” “content-format”: “application/tdlactions+json”, “parameters”:[ {“name”: “targetValue”, “dataType”: “float”},

{“name”: “transitionTime”,

“dataType”:”float”, “units”: “s”}] “template”: “{ “changeTemp”: “$targetValue”,

“transTime”: “$transitionTime” }”, “returns”: [{“responseCode”: “201”,

“responseAction”: “success” “parameters”: [{“type”: “header”,

“name”: “Location”, “type”: “href”

“rel”: “actionInstance” }],

]}To Change the ColorTemperature of /light, POST a template containing targetValue and transition Time parameters to the resource at /light/ColorTemp/Actions. Expect a responseCode of 201 if success and expect to find an actionInstance resource pointed to by the header parameter named “Location”.

Hypertext Form for Step Action hypertext form at resource context = /light/ColorTemp: { “rel”: “action”, “type”: “action”, “name”: “Step”, “method”: “POST”, “href”: “Actions” “content-format”: “application/tdlactions+json”, “parameters”:[ {“name”: “stepSize”, “dataType”: “float”},

{“name”: “transitionTime”,

“dataType”:”float”, “units”: “s”}] “template”: “{ “stepSize”: “$stepSize”,

“transTime”: “$transitionTime” }”, “returns”: [{“responseCode”: “201”,

“responseAction”: “success” “parameters”: [{“type”: “header”,

“name”: “Location”, “type”: “href”

“rel”: “actionInstance” }],

]}To Step the ColorTemperature of /light, POST a template containing stepSize and transition Time parameters to the resource at /light/ColorTemp/Actions. Expect a responseCode of 201 if success and expect to find an actionInstance resource pointed to by the header parameter named “Location”.

Hypertext Form for Move Action hypertext form at resource context = /light/ColorTemp: { “rel”: “action”, “type”: “action”, “name”: “Move”, “method”: “POST”, “href”: “Actions” “content-format”: “application/tdlactions+json”, “parameters”:[ {“name”: “moveRate”, “dataType”: “float”,

“units”: “K/s”}] “template”: “{“rate”: “$moveRate”}”, “returns”: [{“responseCode”: “201”,

“responseAction”: “success” “parameters”: [{“type”: “header”,

“name”: “Location”, “type”: “href”

“rel”: “actionInstance” }],

]}

To Move the ColorTemperature of /light, POST a template containing the moveRate parameter to the resource at /light/ColorTemp/Actions. Expect a responseCode of 201 if success and expect to find an actionInstance resource pointed to by the header parameter named “Location”.

• Can be discovered by the application as the result of a gradual reveal process guided by an ontology, e.g. ColorTemperature control with ChangeValue control semantics

• The name can be rendered to the application based on discovered names populated from well known namespaces e.g. Schema.org

• Actions can be invoked by reusable handlers for well known data and control models

• Example serialization of an action and invocation using discovered names with values supplied from a scene controller: action= my_light.ColorTemperature.Change(targetValue=2900, TransitionTime=10)

• The hypermedia control generates this transaction: POST uri=/light/ColorTemp/Actions pl={“changeTemp”: “2900”, “transTime”: “10”}

• A success response contains the URI of the Action resource in the location header: 201 Created Location: ac3f5774

• Execution of the action can be controlled through the Action resource: action.cancel() DELETE uri=/light/ColorTemp/Actions/ac3f5774

Application Interface Mapping

Hypertext Link – CoAP + IPSO Binding

hypertext link at resource context = /light

{“rel”: “action”,“href”: “3004/0”,“type”: “actuator”,“name”: “ColorTemperature”}

“/light has an action resource at the URI /light/3004/0 of type actuator named ColorTemperature”

Hypertext Form – CoAP + IPSO Binding hypertext form for CoAP binding, resource context = /light/3004/0: { “rel”: “action”, “type”: “action”, “name”: “Change”, “method”: “POST”, “href”: “5052” “content-format”: “application/ipso+senml+json”, “parameters”:[ {“name”: “targetValue”, “dataType”: “float”},

{“name”: “transitionTime”,

“dataType”:”float”, “units”: “s”}] “template”: “[{“n”: “5059”, “v”: “$targetValue”}

{“n”: “5002”, “v”: “$transitionTime”}]”, “returns”: [{“responseCode”: “2.01”,

“responseAction”: “success” “parameters”: [{“type”: “header”,

“name”: “Location”, “type”: “href”

“rel”: “actionInstance” }],

]}To Change the ColorTemperature of /light, POST a template containing targetValue and transition Time parameters to the resource at /light/3004/0/5052. Expect a responseCode of 2.01 if success and expect to find an actionInstance resource pointed to by the header parameter named “Location”

• Example serialization of an action and invocation using discovered names with values supplied from a scene controller: action= my_light.ColorTemperature.Change(targetValue=2900, TransitionTime=10)

• The IPSO + CoAP hypermedia control generates this request: POST uri=/light/3004/0/5052 pl=[{“n”:“5059”,“v”:“2900”},{“n”:“5002”,“v”:“10”}]

• A success response contains the URI of the Action resource in the location header: 2.01 Created Location: 17

• Execution of the action can be controlled through the Action resource: action.cancel() DELETE uri=/light/3004/0/5052/17

Uniform Application Interface, Hypermedia Controls for IPSO + CoAP

References• [Fielding2000]

http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm• [Fielding2008]

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

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

• [Hartke2015] https://tools.ietf.org/html/draft-hartke-core-apps-01 https://tools.ietf.org/html/draft-hartke-core-lighting-00