Hypermedia Design for Machine APIs Web Scale Architecture for the Web of Things Michael 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}” 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 and 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} 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

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

HATEOAS Design for the WoT Interaction Model Resource 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

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 XY temperature change step move targetValue:{units:%} transitionTime rate:{units:%/s} stepSize stop transitionTime:{units:s} change step move targetValue:{units:K, range: } transitionTime rate:{units:K/s} stepSize transitionTime:{units:s} stop light.onOff.change {newState:on} light.color.temperature.change {targetValue:3400, transitionTime:10} light.level.change {targetValue:45, transitionTime:10} thing actuatorsactions parameters application actions {parameters} (colorspace)

Example Hypertext Links to Properties hypertext 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 transaction: 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] [Fielding2008] must-be-hypertext-drivenhttp://roy.gbiv.com/untangled/2008/rest-apis- must-be-hypertext-driven [WEBAPIS] Richardson, L. and M. Amundsen, "RESTful Web APIs”, O'Reilly, September 2013.