David Hume

David Hume's presentation from recent 'Developer Bash' event (http://instil.co/2013/09/18/shiny-bash/).

REST is dead. Long live(d) Hypermedia APIs! Buzzwords aside, though, a perennial problem when attempting to design such APIs is the choice of media type. Atom? Siren? Mint your own? This talk will explore the less obvious choice of HTML5 as the media type for an API along with the challenges faced and the benefits reaped by a real world implementation.

Transcript

1. Good Form Building HyperMedia APIs with HTML David Thomas Hume @dthume http://github.com/dthume
2. APIs
3. Contract Negotiation 2003 We’ll give you an API Sure thing, where do we find the WSDL?
4. RPC :-(
5. REST
6. Contract Negotiation 2013 We’ll give you an API Sweet! Where do we POST the JSON?
8. More RPC :-(
9. “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
10. Hypermedia APIs
11. “Hypermedia Types are MIME media types that contain native hyper-linking semantics that induce application flow.” - Mike Amundsen
12. “The rest of REST” - Jon Moore
13. Hypermedia provides... • Relationships • Direction • Flexibility
14. HTML
15. Data Types and Structures • Lists (<li/>) and Bags (<ul/>) • Maps (<dl/>) • Dates/Times (<time/>) • Machine + Human Readable (<data/>) • Multimedia (<img/>, <audio/>, <video/>)
16. Navigation and Workflow • Direct (<link/>, <a/>) • Parameterised (<form/>)
17. Semantics • Relations (@rel) • Microdata (@itemtype, @itemprop)
18. Microdata
19. 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
20. <div> <div>Latitude: <data value="40.75"> 40 deg 44 min 54.36 sec N </data> </div>, <div>Longitude: <data value="73.98"> 73 deg 59 min 8.5 dec W </data> </div> </div>
21. <div itemscope itemtype="http://schema.org/GeoCoordinates"> <div>Latitude: <data value="40.75"> 40 deg 44 min 54.36 sec N </data> </div>, <div>Longitude: <data value="73.98"> 73 deg 59 min 8.5 dec W </data> </div> </div>
22. <div itemscope itemtype="http://schema.org/GeoCoordinates"> <div>Latitude: <data itemprop="latitude" value="40.75"> 40 deg 44 min 54.36 sec N </data> </div>, <div>Longitude: <data itemprop="longitude" value="73.98"> 73 deg 59 min 8.5 dec W </data> </div> </div>
23. <div itemscope itemtype="http://schema.org/GeoCoordinates"> <div>Latitude: <data itemprop="latitude" value="40.75"> 40 deg 44 min 54.36 sec N </data> </div>, <div>Longitude: <data itemprop="longitude" value="73.98"> 73 deg 59 min 8.5 dec W </data> </div> </div>
24. <article> <h1>System Down</h1> <ul> <li>type 1</li> <li>type 2</li> <li>type 3</li> </ul> <div>Broken</div> <a href="assign">Reassign</a> <a href="reject">Reject</a> </article>
25. <article itemscope itemtype="http://example.com/Issue"> <h1>System Down</h1> <ul> <li>type 1</li> <li>type 2</li> <li>type 3</li> </ul> <div>Broken</div> <a href="assign">Reassign</a> <a href="reject">Reject</a> </article>
26. <article itemscope itemtype="http://example.com/Issue"> <h1 itemprop="name">System Down</h1> <ul> <li>type 1</li> <li>type 2</li> <li>type 3</li> </ul> <div itemprop="description">Broken</div> <a href="assign">Reassign</a> <a href="reject">Reject</a> </article>
27. <article itemscope itemtype="http://example.com/Issue"> <h1 itemprop="name">System Down</h1> <ul> <li itemprop="category">type 1</li> <li itemprop="category">type 2</li> <li itemprop="category">type 3</li> </ul> <div itemprop="description">Broken</div> <a href="assign">Reassign</a> <a href="reject">Reject</a> </article>
28. <article itemscope itemtype="http://example.com/Issue"> <h1 itemprop="name">System Down</h1> <ul> <li itemprop="category">type 1</li> <li itemprop="category">type 2</li> <li itemprop="category">type 3</li> </ul> <div itemprop="description">Broken</div> <a href="assign">Reassign</a> <a href="reject">Reject</a> </article>
29. Links
30. Links provide flow For example: • Related resources • List items • Resources describing available actions
31. <article itemscope itemtype="http://example.com/Issue"> <h1 itemprop="name">System Down</h1> <ul> <li itemprop="category">type 1</li> <li itemprop="category">type 2</li> <li itemprop="category">type 3</li> </ul> <div itemprop="description">Broken</div> <a href="assign">Reassign</a> <a href="reject">Reject</a> </article>
32. Link Relations == Link Semantics • @rel attribute can be used on: ◦ <link/> ◦ <a/> • Expresses the relationship type of the link • Can be used by clients to distinguish links
33. <article itemscope itemtype="http://example.com/Issue"> <h1 itemprop="name">System Down</h1> <ul> <li itemprop="category">type 1</li> <li itemprop="category">type 2</li> <li itemprop="category">type 3</li> </ul> <div itemprop="description">Broken</div> <a rel="http://example.com/AssignAction" href="assign">Reassign</a> <a rel="http://example.com/RejectAction" href="reject">Reject</a> </article>
34. <head> <link href="next" rel="next" /> <link href="prev" rel="prev" /> </head>
35. Forms
36. <form action="search" method="GET" enctype="application/x-www-form-urlencoded"> <label for="q">Query</label> <input id="q" name="q" type="text" value="red wedding" /> <input type="submit" value="Search" /> </form> Describe possible requests
37. <form action="search" method="GET" enctype="application/x-www-form-urlencoded"> <label for="q">Query</label> <input id="q" name="q" type="text" value="red wedding" /> <input type="submit" value="Search" /> </form> Where the request can be sent
38. <form action="search" method="GET" enctype="application/x-www-form-urlencoded"> <label for="q">Query</label> <input id="q" name="q" type="text" value="red wedding" /> <input type="submit" value="Search" /> </form> How the request can be made
39. <form action="search" method="GET" enctype="application/x-www-form-urlencoded"> <label for="q">Query</label> <input id="q" name="q" type="text" value="red wedding" /> <input type="submit" value="Search" /> </form> What (media) type can be sent
40. <form action="search" method="GET" enctype="application/x-www-form-urlencoded"> <label for="q">Query</label> <input id="q" name="q" type="text" value="red wedding" /> <input type="submit" value="Search" /> </form> What data can be sent...
41. <form action="search" method="GET" enctype="application/x-www-form-urlencoded"> <label for="q">Query</label> <input id="q" name="q" type="text" value="red wedding" /> <input type="submit" value="Search" /> </form> ...and what defaults can it have
42. <form action="search" method="GET" enctype="application/x-www-form-urlencoded"> <label for="q">Query</label> <input id="q" name="q" type="text" value="red wedding" /> <input type="submit" value="Search" /> </form> What submissions can be made
43. <select name="house"> <option value="baratheon">Baratheon</option> <option value="greyjoy">Greyjoy</option> <option value="lannister">Lannister</option> <option value="targaryen">Targaryen</option> <option value="stark">Stark</option> </select> Express Choice
44. <input name="q" type="text" required /> <input name="q" type="text" multiple /> Required Fields / Arity
45. <form action="search" method="GET" enctype="application/x-www-form-urlencoded" data-rel="search"> <label for="q">Query</label> <input id="q" name="q" type="text" value="red wedding" /> <input type="submit" value="Search" /> </form> Extend with relation semantics
46. So we’re armed with • Structure • Relationships • Semantics
47. “A good REST API is like an ugly website” - Rickard Oberg
48. Show me the Markup
49. Conclusions
50. Working with HTML APIs • CSS Selectors (jQuery, JSoup, Jerry etc.) • XML (if you must: DOM/SAX etc.)
51. 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
52. The Bad • Easy to forget target audience (machines) • Spec weaknesses: ◦ No PUT or DELETE support (yet) ◦ Use of @data-rel on <form/>s not standard ◦ Value of <input/>s with @itemprop not standard • Arguably verbose
53. 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
54. 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/
55. Questions?