Slide 1
Slide 1 text
Good Form
Building HyperMedia APIs with HTML
David Thomas Hume
@dthume
http://github.com/dthume
Slide 2
Slide 2 text
APIs
Slide 3
Slide 3 text
Contract Negotiation 2003
We’ll give you an API
Sure thing, where do we find the WSDL?
Slide 4
Slide 4 text
RPC :-(
Slide 5
Slide 5 text
REST
Slide 6
Slide 6 text
Contract Negotiation 2013
We’ll give you an API
Sweet! Where do we POST the JSON?
Slide 7
Slide 7 text
No content
Slide 8
Slide 8 text
More RPC :-(
Slide 9
Slide 9 text
“If the API is not being driven by hypertext,
then it cannot be RESTful and cannot be a
REST API. Period. Is there some broken
manual somewhere that needs to be fixed?”
- Roy Fielding
Slide 10
Slide 10 text
Hypermedia APIs
Slide 11
Slide 11 text
“Hypermedia Types are MIME media types
that contain native hyper-linking semantics
that induce application flow.”
- Mike Amundsen
Slide 12
Slide 12 text
“The rest of REST”
- Jon Moore
Slide 13
Slide 13 text
Hypermedia provides...
● Relationships
● Direction
● Flexibility
Slide 14
Slide 14 text
HTML
Slide 15
Slide 15 text
Data Types and Structures
● Lists () and Bags (
- )
● Maps (
- )
● Dates/Times (
Slide 17
Slide 17 text
Semantics
● Relations (@rel)
● Microdata (@itemtype, @itemprop)
Slide 18
Slide 18 text
Microdata
Slide 19
Slide 19 text
Provides elements with semantics
● Adds meaning to structure
● Like the _type property common in JSON
● Can use existing “standard” types
○ http://schema.org
● Or use custom types if required
Slide 20
Slide 20 text
Latitude:
40 deg 44 min 54.36 sec N
,
Longitude:
73 deg 59 min 8.5 dec W
Slide 21
Slide 21 text
Latitude:
40 deg 44 min 54.36 sec N
,
Longitude:
73 deg 59 min 8.5 dec W
Slide 22
Slide 22 text
Latitude:
40 deg 44 min 54.36 sec N
,
Longitude:
73 deg 59 min 8.5 dec W
Slide 23
Slide 23 text
Latitude:
40 deg 44 min 54.36 sec N
,
Longitude:
73 deg 59 min 8.5 dec W
Slide 29
Slide 29 text
Links
Slide 30
Slide 30 text
Links provide flow
For example:
● Related resources
● List items
● Resources describing available actions
Slide 32
Slide 32 text
Link Relations == Link Semantics
● @rel attribute can be used on:
○
○
● Expresses the relationship type of the link
● Can be used by clients to distinguish links
Slide 34
Slide 34 text
Slide 35
Slide 35 text
Forms
Slide 36
Slide 36 text
Query
Describe possible requests
Slide 37
Slide 37 text
Query
Where the request can be sent
Slide 38
Slide 38 text
Query
How the request can be made
Slide 39
Slide 39 text
Query
What (media) type can be sent
Slide 40
Slide 40 text
Query
What data can be sent...
Slide 41
Slide 41 text
Query
...and what defaults can it have
Slide 42
Slide 42 text
Query
What submissions can be made
Slide 43
Slide 43 text
Baratheon
Greyjoy
Lannister
Targaryen
Stark
Express Choice
Slide 44
Slide 44 text
Required Fields / Arity
Slide 45
Slide 45 text
Query
Extend with relation semantics
Slide 46
Slide 46 text
So we’re armed with
● Structure
● Relationships
● Semantics
Slide 47
Slide 47 text
“A good REST API is like an ugly website”
- Rickard Oberg
Slide 48
Slide 48 text
Show me the Markup
Slide 49
Slide 49 text
Conclusions
Slide 50
Slide 50 text
Working with HTML APIs
● CSS Selectors (jQuery, JSoup, Jerry etc.)
● XML (if you must: DOM/SAX etc.)
Slide 51
Slide 51 text
The Good
● Explore / Debug / Test - Use a browser
○ No firebug needed! (though still useful)
● Decent support for most languages
● Specs for HTML itself
○ Still need to document @rel and @itemtype use
Slide 52
Slide 52 text
The Bad
● Easy to forget target audience (machines)
● Spec weaknesses:
○ No PUT or DELETE support (yet)
○ Use of @data-rel on s not standard
○ Value of s with @itemprop not standard
● Arguably verbose
Slide 53
Slide 53 text
Application-as-API
● Users want their UI on top of your services
● And they want everything your app can do
● Make the app the API
● Works well with ROCA
Slide 54
Slide 54 text
References
● http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hypertext-driven
● https://github.com/Comcast/htmlapi-client-python
● http://codeartisan.blogspot.co.uk/2012/07/using-html-as-
media-type-for-your-api.html
● http://roca-style.org/
Slide 55
Slide 55 text
Questions?