Hypermedia Design for Machine APIs Web Scale Architecture

Hypermedia Design for Machine APIs Web Scale Architecture for the Web of Things Michael J Koster 14 September 2015

Fielding 4. 3 [Fielding 2000] • 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? Application Representations of State Information Resource • 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

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 <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} • 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 • Co. RE Link Format (RFC 6690) • JSON-LD – Wo. T 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 Wo. T 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 Wo. T 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 thing actuators on. Off actions parameters change new. State: {enum: off, on} toggle change light level step move stop color (colorspace) change HS step temperature move XY stop application actions {parameters} light. on. Off. change {new. State: on} target. Value: {units: %} transition. Time: {units: s} step. Size light. level. change transition. Time {target. Value: 45, rate: {units: %/s} transition. Time: 10} target. Value: {units: K, range: 2700 -5500} transition. Time: {units: s} step. Size transition. Time rate: {units: K/s} light. color. temperature. change {target. Value: 3400, transition. Time: 10}

Example Hypertext Links to Properties hypertext links at resource context = /light [{ “rel”: “property”, “href”: “Color. Temp/current. Value”, “type”: “observable”, “name”: “Color. Temperature” }, { “rel”: “property”, “href”: “Color. Temp/rem. Time”, “type”: “observable”, “name”: “Transition. Time. Remaining” }] /light has observable property resources: “Color. Temperature” at the URI /light/Color. Temp/current. Value “Transition. Time. Remaining” at the URI /light/Color. Temp/rem. Time

Hypertext Link to Actuator hypertext link at resource context = /light { “rel”: “action”, “href”: “Color. Temp”, “type”: “actuator”, “name”: “Color. Temperature” } “/light has an actuator type action resource named Color. Temperature at the URI /light/Color. Temp”

Hypertext Form for Change Action hypertext form at resource context = /light/Color. Temp: { “rel”: “action”, “type”: “action”, “name”: “Change”, “method”: “POST”, “href”: “Actions” “content-format”: “application/tdlactions+json”, “parameters”: [ {“name”: “target. Value”, “data. Type”: “float”}, {“name”: “transition. Time”, “data. Type”: ”float”, “units”: “s”}] “template”: “{ “change. Temp”: “$target. Value”, “trans. Time”: “$transition. Time” }”, “returns”: [{“response. Code”: “ 201”, “response. Action”: “success” “parameters”: [{“type”: “header”, “name”: “Location”, “type”: “href” “rel”: “action. Instance” }], ]} To Change the Color. Temperature of /light, POST a template containing target. Value and transition Time parameters to the resource at /light/Color. Temp/Actions. Expect a response. Code of 201 if success and expect to find an action. Instance resource pointed to by the header parameter named “Location”.

Hypertext Form for Step Action hypertext form at resource context = /light/Color. Temp: { “rel”: “action”, “type”: “action”, “name”: “Step”, “method”: “POST”, “href”: “Actions” “content-format”: “application/tdlactions+json”, “parameters”: [ {“name”: “step. Size”, “data. Type”: “float”}, {“name”: “transition. Time”, “data. Type”: ”float”, “units”: “s”}] “template”: “{ “step. Size”: “$step. Size”, “trans. Time”: “$transition. Time” }”, “returns”: [{“response. Code”: “ 201”, “response. Action”: “success” “parameters”: [{“type”: “header”, “name”: “Location”, “type”: “href” “rel”: “action. Instance” }], ]} To Step the Color. Temperature of /light, POST a template containing step. Size and transition Time parameters to the resource at /light/Color. Temp/Actions. Expect a response. Code of 201 if success and expect to find an action. Instance resource pointed to by the header parameter named “Location”.

Hypertext Form for Move Action hypertext form at resource context = /light/Color. Temp: { “rel”: “action”, “type”: “action”, “name”: “Move”, “method”: “POST”, “href”: “Actions” “content-format”: “application/tdlactions+json”, “parameters”: [ {“name”: “move. Rate”, “data. Type”: “float”, “units”: “K/s”}] “template”: “{“rate”: “$move. Rate”}”, “returns”: [{“response. Code”: “ 201”, “response. Action”: “success” “parameters”: [{“type”: “header”, “name”: “Location”, “type”: “href” “rel”: “action. Instance” }], ]} To Move the Color. Temperature of /light, POST a template containing the move. Rate parameter to the resource at /light/Color. Temp/Actions. Expect a response. Code of 201 if success and expect to find an action. Instance resource pointed to by the header parameter named “Location”.

Application Interface Mapping • Can be discovered by the application as the result of a gradual reveal process guided by an ontology, e. g. Color. Temperature control with Change. Value 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. Color. Temperature. Change(target. Value=2900, Transition. Time=10) • The hypermedia control generates this transaction: POST uri=/light/Color. Temp/Actions pl={“change. Temp”: “ 2900”, “trans. Time”: “ 10”} • A success response contains the URI of the Action resource in the location header: 201 Created Location: ac 3 f 5774 • Execution of the action can be controlled through the Action resource: action. cancel() DELETE uri=/light/Color. Temp/Actions/ac 3 f 5774

Hypertext Link – Co. AP + IPSO Binding hypertext link at resource context = /light { “rel”: “action”, “href”: “ 3004/0”, “type”: “actuator”, “name”: “Color. Temperature” } “/light has an action resource at the URI /light/3004/0 of type actuator named Color. Temperature”

Hypertext Form – Co. AP + IPSO Binding hypertext form for Co. AP binding, resource context = /light/3004/0: { “rel”: “action”, “type”: “action”, “name”: “Change”, “method”: “POST”, “href”: “ 5052” “content-format”: “application/ipso+senml+json”, “parameters”: [ {“name”: “target. Value”, “data. Type”: “float”}, {“name”: “transition. Time”, “data. Type”: ”float”, “units”: “s”}] “template”: “[{“n”: “ 5059”, “v”: “$target. Value”} {“n”: “ 5002”, “v”: “$transition. Time”}]”, “returns”: [{“response. Code”: “ 2. 01”, “response. Action”: “success” “parameters”: [{“type”: “header”, “name”: “Location”, “type”: “href” “rel”: “action. Instance” }], ]} To Change the Color. Temperature of /light, POST a template containing target. Value and transition Time parameters to the resource at /light/3004/0/5052. Expect a response. Code of 2. 01 if success and expect to find an action. Instance resource pointed to by the header parameter named “Location”

Uniform Application Interface, Hypermedia Controls for IPSO + Co. AP • Example serialization of an action and invocation using discovered names with values supplied from a scene controller: action= my_light. Color. Temperature. Change(target. Value=2900, Transition. Time=10) • The IPSO + Co. AP 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

References • [Fielding 2000] http: //www. ics. uci. edu/~fielding/pubs/dissertation/top. htm • [Fielding 2008] http: //roy. gbiv. com/untangled/2008/rest-apismust-be-hypertext-driven • [WEBAPIS] Richardson, L. and M. Amundsen, "RESTful Web APIs”, O'Reilly, September 2013.