Hypermedia design for machine apis

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}” [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 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

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
XY
temperature
change
step
move
targetValue:{units:%}
transitionTime
rate:{units:%/s}
stepSize
stop
transitionTime:{units:s}
change
step
move
targetValue:{units:K,
range:2700-5500}
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 actuators actions 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”,
}
“/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
{
“rel”: “action”, “type”: “action”, “name”: “Step”,
“parameters”:[ {“name”: “stepSize”, “dataType”: “float”},
“template”: “{ “stepSize”: “$stepSize”,
“transTime”: “$transitionTime” }”,
]}
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
{
“rel”: “action”, “type”: “action”, “name”: “Move”,
“parameters”:[ {“name”: “moveRate”, “dataType”: “float”,
“units”: “K/s”}]
“template”: “{“rate”: “$moveRate”}”,
]}
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”,
}
“/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”},
“template”: “[{“n”: “5059”, “v”: “$targetValue”}
{“n”: “5002”, “v”: “$transitionTime”}]”,
“returns”: [{“responseCode”: “2.01”,
]}
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

Hypermedia design for machine apis

More Related Content

What's hot

Similar to Hypermedia design for machine apis

More from Michael Koster

Recently uploaded

Hypermedia design for machine apis