The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012...
Transcript of The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012...
![Page 1: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/1.jpg)
Layer 7 Confidential 1
Mike Amundsen
The Costs and Benefits of
Building Hypermedia APIs
(with Node.js)
![Page 2: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/2.jpg)
Layer 7 Confidential 2
Mike Amundsen
Author
Presenter
Software Explorer
Principal API Architect
![Page 3: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/3.jpg)
Layer 7 Confidential 3
OK, let’s get started…
![Page 4: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/4.jpg)
Layer 7 Confidential 4
Theonia "a looking at, viewing, beholding”
![Page 5: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/5.jpg)
Layer 7 Confidential 5
Theory "a looking at, viewing, beholding”
![Page 6: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/6.jpg)
Layer 7 Confidential 6
Praxis “doing”
![Page 7: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/7.jpg)
Layer 7 Confidential 7
Practice “doing”
![Page 8: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/8.jpg)
Layer 7 Confidential 8
First, a lesson to remember
from Donald Norman…
![Page 9: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/9.jpg)
Layer 7 Confidential 10
Affordances
“The value of a well-designed object,
Is when it has such a rich set of affordances,
That the people who use it,
Can do things with it,
That the designer never imagined.”
- Donald Norman
![Page 10: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/10.jpg)
Layer 7 Confidential 11
Affordances
“The value of a well-designed object,
Is when it has such a rich set of affordances,
That the people who use it,
Can do things with it,
That the designer never imagined.”
- Donald Norman
![Page 11: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/11.jpg)
Layer 7 Confidential 12
Affordances
“The value of a well-designed object,
Is when it has such a rich set of affordances,
That the people who use it,
Can do things with it,
That the designer never imagined.”
- Donald Norman
![Page 12: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/12.jpg)
Layer 7 Confidential 13
Affordances
“The value of a well-designed object,
Is when it has such a rich set of affordances,
That the people who use it,
Can do things with it,
That the designer never imagined.”
- Donald Norman
![Page 13: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/13.jpg)
Layer 7 Confidential 14
Affordances
“The value of a well-designed object,
Is when it has such a rich set of affordances,
That the people who use it,
Can do things with it,
That the designer never imagined.”
- Donald Norman
![Page 14: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/14.jpg)
Layer 7 Confidential 15
Some background…
![Page 15: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/15.jpg)
Layer 7 Confidential 16
Affordances
The foundation for perception is ambient,
ecologically available information.
Affordances are all "action possibilities" latent in
the environment.
Theory of Affordances, 1979
- James J. Gibson
![Page 16: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/16.jpg)
Layer 7 Confidential 17
Seven Stages of Action Affordances
The Design of Everyday Things, 1988
- Donald Norman
![Page 17: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/17.jpg)
Layer 7 Confidential 18
Affordances Knowledge (“head” vs. “world”)
April 17, 2012 APIs to Affordances : WS-REST 2012 18
Property Knowledge in the
World Knowledge in the Head
Learning
Learning not required.
Interpretation
substitutes for learning.
How easy it is to
interpret information is
the world depends
upon how well it
exploits natural
mappings and
constraints.
Requires learning, which
can be considerable.
Learning is made easier if
there is meaning of
structure to the material (or
if there is a good mental
model).
Efficiency
of use
Tends to be slowed up
by the need to find and
interpret the external
information.
Can be very efficient
Ease of use
at first
encounter
High Low
![Page 18: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/18.jpg)
Layer 7 Confidential 19
Affordances
"Hypermedia is defined by the presence of application
control information embedded within, or as a layer above,
the presentation of information“ (2001)
“When I say [Hypermedia], I mean the simultaneous
presentation of information and controls such that the
information becomes the affordance through which the user
obtains choices and selects actions” (2008)
Architectural Styles and the Design
of Network-based Software, 2001
- Roy T. Fielding
![Page 19: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/19.jpg)
Layer 7 Confidential 20
Affordances
"Hypermedia is defined by the presence of application
control information embedded within, or as a layer above,
the presentation of information“ (2001)
“When I say [Hypermedia], I mean the simultaneous
presentation of information and controls such that the
information becomes the affordance through which the user
obtains choices and selects actions” (2008)
Architectural Styles and the Design
of Network-based Software, 2001
- Roy T. Fielding
![Page 20: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/20.jpg)
Layer 7 Confidential 21
Affordances
Affordances
make
Hypermedia
possible.
![Page 21: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/21.jpg)
Layer 7 Confidential 22
Affordances
Hypermedia
can provide a
Rich Set of Affordances
![Page 22: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/22.jpg)
Layer 7 Confidential 23
Maze+XML
Design #1:
A big pile of Affordances
![Page 23: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/23.jpg)
Layer 7 Confidential 24
Maze+XML
Maze+XML media type
First design in late 2010, registered w/ IANA 2011
“…an XML data format for sharing maze state information
between clients and servers. It can be used to implement
simple mazes, adventure games, and other related data.”
Read-only navigational links
Nine link identifiers:
collection, maze, start, exit, current,
north, south, east, west
![Page 24: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/24.jpg)
Layer 7 Confidential 25
Maze+XML Message
![Page 25: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/25.jpg)
Layer 7 Confidential 26
Maze+XML Server
![Page 26: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/26.jpg)
Layer 7 Confidential 27
Maze+XML Client
![Page 27: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/27.jpg)
Layer 7 Confidential 28
Maze+XML Client
![Page 28: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/28.jpg)
Layer 7 Confidential 29
Maze+XML Client
![Page 29: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/29.jpg)
Layer 7 Confidential 30
Maze+XML Client Code
![Page 30: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/30.jpg)
Layer 7 Confidential 31
Maze+XML
In the wild…
![Page 31: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/31.jpg)
Layer 7 Confidential 32
Maze+XML
Darrel Miller
“A good example of using link relations to convey
domain specific semantics.”
“Has been a good test bed for trying to develop a UI
transparently that tracks the state of the user agent as it
navigates between representations.”
![Page 32: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/32.jpg)
Layer 7 Confidential 33
Maze+XML Darrel Miller – C#
![Page 33: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/33.jpg)
Layer 7 Confidential 34
Yannick Loiseau
“I can say that a non-restful architecture would have been a
lot harder to deal with in bash, because hypermedia
obviously made the maze exploration really easy”
“I think that Link headers would be even
easier to deal with…”
Maze+XML
![Page 34: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/34.jpg)
Layer 7 Confidential 35
Yannick Loiseau - Python Maze+XML
![Page 35: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/35.jpg)
Layer 7 Confidential 36
Yannick Loiseau - Bash Maze+XML
![Page 36: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/36.jpg)
Layer 7 Confidential 37
Maze+XML
Characteristics
- Read-Only navigational links
- Limited set of identifiers
- Domain specific
Benefits
- Simple, direct design
- Easy to create servers/clients
- M2M works when algorithm is available
Costs
- Limited reach
- M2M clients challenge evolvability
![Page 37: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/37.jpg)
Layer 7 Confidential 38
H-Factors
“Pardon me, did you say ‘links’?”
![Page 38: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/38.jpg)
Layer 7 Confidential 39
“The H Factor of a media-type is a measure of the
level of hypermedia support within that media-type.”
“H Factor values can be used to compare and
contrast media types in order to aid in selecting the
proper media-type(s) for your
implementation.”
H-Factors
REST: From Research to Practice :
Hypermedia Types, 2011
- Mike Amundsen
![Page 39: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/39.jpg)
Layer 7 Confidential 40
H-Factors Analyzing Media Types
![Page 40: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/40.jpg)
Layer 7 Confidential 41
H-Factors Analyzing Media Types
![Page 41: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/41.jpg)
Layer 7 Confidential 42
H-Factors Analyzing Media Types
![Page 42: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/42.jpg)
Layer 7 Confidential 43
H-Factors
There are five LINK Factors
(LO, LE, LT, LI, LN)
There are four CONTROL Factors
(CR, CU, CM, CL)
![Page 43: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/43.jpg)
Layer 7 Confidential 44
H-Factors
There are five LINK Factors
(LO, LE, LT, LI, LN)
There are four CONTROL Factors
(CR, CU, CM, CL)
![Page 44: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/44.jpg)
Layer 7 Confidential 45
H-Factors Linking
Outbound Links (LO)
![Page 45: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/45.jpg)
Layer 7 Confidential 46
H-Factors Linking
Outbound Links (LO)
Embedded Links (LE)
![Page 46: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/46.jpg)
Layer 7 Confidential 47
H-Factors Linking
Outbound Links (LO)
Embedded Links (LE)
Templated Links (LT)
![Page 47: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/47.jpg)
Layer 7 Confidential 48
H-Factors Linking
Outbound Links (LO)
Embedded Links (LE)
Templated Links (LT)
Idempotent Links (LI)
![Page 48: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/48.jpg)
Layer 7 Confidential 49
H-Factors Linking
Outbound Links (LO)
Embedded Links (LE)
Templated Links (LT)
Idempotent Links (LI)
Non-Idempotent Links (LN)
![Page 49: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/49.jpg)
Layer 7 Confidential 50
H-Factors
There are five LINK Factors
(LO, LE, LT, LI, LN)
There are four CONTROL Factors
(CR, CU, CM, CL)
![Page 50: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/50.jpg)
Layer 7 Confidential 51
H-Factors Control
Request Controls (CR)
![Page 51: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/51.jpg)
Layer 7 Confidential 52
H-Factors Control
Request Controls (CR)
Update Controls (CU)
![Page 52: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/52.jpg)
Layer 7 Confidential 53
H-Factors Control
Request Controls (CR)
Update Controls (CU)
Method Controls (CM)
![Page 53: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/53.jpg)
Layer 7 Confidential 54
H-Factors Control
Request Controls (CR)
Update Controls (CU)
Method Controls (CM)
Link Controls (CL)
![Page 54: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/54.jpg)
Layer 7 Confidential 55
H-Factors
A pre-defined collection of H-Factors is called a
“Media Type”
Each media type has it’s own “H-Factor” signature.
![Page 55: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/55.jpg)
Layer 7 Confidential 56
H-Factors
H-Factors document
the Affordances
of the
Media Type
![Page 56: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/56.jpg)
Layer 7 Confidential 57
H-Factors
“OK, media types, affordances, I see…
![Page 57: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/57.jpg)
Layer 7 Confidential 58
Collection+JSON
Design #2:
A read/write hypermedia type
![Page 58: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/58.jpg)
Layer 7 Confidential 59
Collection+JSON
Collection+JSON media type
First designs in early 2011, registered w/ IANA mid 2011
“…a JSON-based read/write hypermedia-type designed to
support management and querying of simple collections.”
It’s Atom w/ LT + templated writes
Very limited link identifiers
- collection, item, templates, query
![Page 59: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/59.jpg)
Layer 7 Confidential 60
Message Collection+JSON
![Page 60: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/60.jpg)
Layer 7 Confidential 61
Message Collection+JSON
![Page 61: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/61.jpg)
Layer 7 Confidential 62
Message Collection+JSON
![Page 62: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/62.jpg)
Layer 7 Confidential 63
Message Collection+JSON
![Page 63: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/63.jpg)
Layer 7 Confidential 64
Message Collection+JSON
![Page 64: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/64.jpg)
Layer 7 Confidential 65
Server Collection+JSON
![Page 65: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/65.jpg)
Layer 7 Confidential 66
Server Collection+JSON
![Page 66: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/66.jpg)
Layer 7 Confidential 67
Server Collection+JSON
![Page 67: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/67.jpg)
Layer 7 Confidential 68
Client Code Collection+JSON
![Page 68: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/68.jpg)
Layer 7 Confidential 69
Client Code Collection+JSON
![Page 69: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/69.jpg)
Layer 7 Confidential 70
Client Code Collection+JSON
![Page 70: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/70.jpg)
Layer 7 Confidential 71
Client App
Collection+JSON
![Page 71: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/71.jpg)
Layer 7 Confidential 72
Client App
Collection+JSON
![Page 72: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/72.jpg)
Layer 7 Confidential 73
Collection+JSON
In the wild…
![Page 73: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/73.jpg)
Layer 7 Confidential 74
Collection+JSON
Nokia Research - Live Mixed Reality - Vlad Stribu
“[Collection+JSON] … allows us to develop authoring tools
that have the ability to self-adapt the user interface to the
usage context.”
![Page 74: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/74.jpg)
Layer 7 Confidential 75
Collection+JSON
Nokia Research - Live Mixed Reality - Vlad Stribu
“Collection+JSON was close enough to what we were
looking for…”
“Most important factor that influenced our decision was the
community around this format…”
![Page 75: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/75.jpg)
Layer 7 Confidential 76
Collection+JSON
CloudApp – Larry Marburger
“CloudApp allows you to share images, links, music, videos
and files.”
“[Due to developer team changes] we had some setbacks
with the Mac app and subsequently the API. We just started
working with another developer who's making amazing
progress.”
![Page 76: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/76.jpg)
Layer 7 Confidential 77
Collection+JSON
ember.js – Yehuda Katz
“A framework for creating ambitious applications.”
“By default, it's somewhat repetitive, but that can be
addressed…”
“It was straight-forward to extend it with features I needed”
“I am starting to feel like with the number of extensions, I
should consider [creating] my own media type.”
![Page 77: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/77.jpg)
Layer 7 Confidential 78
Collection+JSON
Characteristics
- Read/Write w/ Templates
- Small set of link identifiers
- General “List Domain” handler
Benefits
- Limited design means simple parser
- Servers easy, clients harder
- Built-in support for custom domain annotations
Costs
- Domain mapping is more difficult
- M2M clients limited to pre-declared vocabulary
![Page 78: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/78.jpg)
Layer 7 Confidential 79
Affordance Aspects
“So, are all affordances essentially
the same?”
![Page 79: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/79.jpg)
Layer 7 Confidential 80
Affordance Aspects
“For the purposes of applying affordances to
hypermedia, there are four important aspects
to consider”
![Page 80: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/80.jpg)
Layer 7 Confidential 81
Affordance Aspects
Safe
The HTTP protocol supports a number of "safe"
actions such as HEAD, and GET.
![Page 81: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/81.jpg)
Layer 7 Confidential 82
Affordance Aspects
Safe
The HTTP protocol supports a number of "safe"
actions such as HEAD, and GET.
The HTTP methods PUT, POST, and DELETE are
categorized as "unsafe" actions.
![Page 82: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/82.jpg)
Layer 7 Confidential 83
Affordance Aspects
Idempotent
When an HTML:FORM element has the METHOD
property set to "get" it represents an idempotent
action.
![Page 83: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/83.jpg)
Layer 7 Confidential 84
Affordance Aspects
Idempotent
When an HTML:FORM element has the METHOD
property set to "get" it represents an idempotent
action.
When the same property is set to "post" the
affordance represents a non-idempotent action.
![Page 84: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/84.jpg)
Layer 7 Confidential 85
Affordance Aspects
Mutability
HTML:FORM affords mutability
![Page 85: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/85.jpg)
Layer 7 Confidential 86
Affordance Aspects
Mutability
HTML:FORM affords mutability
HTML:LINK is immutable
![Page 86: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/86.jpg)
Layer 7 Confidential 87
Affordance Aspects
Transclusion
HTML:IMG affords transclusion
![Page 87: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/87.jpg)
Layer 7 Confidential 88
Affordance Aspects
Transclusion
HTML:IMG affords transclusion
HTML:A does not
![Page 88: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/88.jpg)
Layer 7 Confidential 89
Affordance Aspects
However, this single affordance is not
very usable.
![Page 89: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/89.jpg)
Layer 7 Confidential 90
Affordance Aspects
Media types
should be
usable
![Page 90: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/90.jpg)
Layer 7 Confidential 91
Affordance Aspects
Messages
should be
usable
![Page 91: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/91.jpg)
Layer 7 Confidential 92
Affordance Aspects
APIs
should be
usable
![Page 92: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/92.jpg)
Layer 7 Confidential 93
ALPS for HTML
Design #3:
Aspects, Factors, Abstractions
![Page 93: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/93.jpg)
Layer 7 Confidential 94
ALPS for HTML
ALPS profile URI
First designs in early 2011 (not registered)
“The purpose of Application-Level Profile Semantics (ALPS)
is to document the application-level semantics of a particular
implementation.”
“The example profile here contains details
on customizing the XHTML media type
for a specific application domain:
Micro-blogging.”
![Page 94: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/94.jpg)
Layer 7 Confidential 95
ALPS for HTML
ALPS profile URI
Multiple parties building their own client or server
applications without seeing each other's work or accessing a
running "reference" implementation.
Developers are expected to rely on the constraints and
definitions found in this document (and the referenced
RFCs) as the sole instruction.
![Page 95: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/95.jpg)
Layer 7 Confidential 96
ALPS for HTML Messages
![Page 96: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/96.jpg)
Layer 7 Confidential 97
ALPS for HTML Messages
![Page 97: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/97.jpg)
Layer 7 Confidential 98
ALPS for HTML Messages
![Page 98: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/98.jpg)
Layer 7 Confidential 99
ALPS for HTML Server Code
![Page 99: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/99.jpg)
Layer 7 Confidential 100
ALPS for HTML Client Code
![Page 100: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/100.jpg)
Layer 7 Confidential 101
ALPS for HTML Client App
![Page 101: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/101.jpg)
Layer 7 Confidential 102
ALPS for HTML Client Bot
![Page 102: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/102.jpg)
Layer 7 Confidential 103
ALPS for HTML Client Bot
![Page 103: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/103.jpg)
Layer 7 Confidential 104
ALPS for HTML Client Bot
![Page 104: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/104.jpg)
Layer 7 Confidential 105
ALPS for HTML
“In the wild…”
![Page 105: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/105.jpg)
Layer 7 Confidential 106
ALPS for HTML
Rstat.us – Carol Nichols
“There are two things that make rstat.us special: simplicity
and openness.”
“[S]ince we already have a full-functioning end-user facing
site, the ALPS microblogging spec means adding a few
attributes rather than having to maintain a totally separate
API interface.”
“The current way of
presenting the ALPS
spec is [too] flat.”
![Page 106: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/106.jpg)
Layer 7 Confidential 107
ALPS for HTML
Rstat.us – Carol Nichols
![Page 107: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/107.jpg)
Layer 7 Confidential 108
ALPS for HTML
Rstat.us – Carol Nichols
![Page 108: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/108.jpg)
Layer 7 Confidential 109
ALPS for HTML
Characteristics
- Domain Semantics Only
- Media-type agnostic
Benefits
- Focused on problem domain
- Treats “pages” as the “API”
Costs
- Very abstract model
- Tough to document
- Seems “over complex” esp. for M2M cases
![Page 109: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/109.jpg)
Layer 7 Confidential 110
ALPS for HTML
“If HTML is not the only media-type
we need…”
![Page 110: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/110.jpg)
Layer 7 Confidential 111
ALPS for HTML
“How do you choose?”
![Page 111: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/111.jpg)
Layer 7 Confidential 112
Methodology
Mapping your domain to HTTP
![Page 112: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/112.jpg)
Layer 7 Confidential 113
Designing messages is the primary work
Focus on mapping to payloads, not identifiers
Survey existing media types first
If you can’t find a suitable H-Factor signature
match, consider designing your own.
Pro Tip: you can always find a match.
Methodology
![Page 113: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/113.jpg)
Layer 7 Confidential 114
Start with a format (XML, JSON, HTML, etc.)
You might need to support more than one
Don’t assume you can “cross-map” formats easily
Pro Tip: you almost always need to support more
than one.
Methodology
![Page 114: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/114.jpg)
Layer 7 Confidential 115
Select your other design elements as needed
Methodology
![Page 115: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/115.jpg)
Layer 7 Confidential 116
Represent State, not Objects
Remember both data and transitions
Craft lots of messages
Pro Tip: you can never have enough messages
Methodology
![Page 116: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/116.jpg)
Layer 7 Confidential 117
When you are sure you have:
The proper format
The right H-Factor signature
The correct mapping of domain to messages
Sufficent message examples
Then, and only then…
Methodology
![Page 117: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/117.jpg)
Layer 7 Confidential 118
You can start writing
the code
Methodology
![Page 118: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/118.jpg)
Layer 7 Confidential 119
Because…
Methodology
![Page 119: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/119.jpg)
Layer 7 Confidential 120
The code is only
the implementation
Methodology
![Page 120: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/120.jpg)
Layer 7 Confidential 121
The code is only
the implementation
The media type is
the design.
Methodology
![Page 121: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/121.jpg)
Layer 7 Confidential 122
And if you get the design
right...
Methodology
![Page 122: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/122.jpg)
Layer 7 Confidential 123
Your users will be able
to do things
Methodology
![Page 123: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/123.jpg)
Layer 7 Confidential 124
Your users will be able
to do things
Methodology
![Page 124: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/124.jpg)
Layer 7 Confidential 125
Your users will be able
to do things
you never imagined
Methodology
![Page 125: The Costs and Benefits of Building Hypermedia APIs (with Node.js) · 2013-05-20 · April 17, 2012 APIs to Affordances : WS-REST 2012 18 Property Knowledge in the World Knowledge](https://reader034.fdocuments.us/reader034/viewer/2022050116/5f4d08493c53810fcb550b3b/html5/thumbnails/125.jpg)
Layer 7 Confidential 126
Mike Amundsen
The Costs and Benefits of
Building Hypermedia APIs
(with Node.js)
@mamund