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 (16)

Similar to Hypermedia design for machine apis (20)

More from Michael Koster (12)

Recently uploaded (20)

Hypermedia design for machine apis