Loveable Hypermedia APIs

This was a talk given at APIDays 2012 about creating hypermedia APIs that find a balance which maintains some evolvability whilst providing a good developer experience. In other words, it was a sales pitch for hal+json. ;)

Transcript

1. Loveable Hypermedia APIs Mike Kelly @mikekelly85 mike@stateless.co #apidays
2. application/hal+json
3. Hypermedia Clients progress through application via “control elements” contained within the messages
4. HTML’s control elements <link> <form> <a> <img> etc..
5. JSON’s control elements Uhhh…
6. JSON’s control elements
7. application/hal+json application/collection+json application/siren+json application/home-json
8. Why bother? Evolvability:
9. JSON API maintenance: an analogy
10. JSON API maintenance: an analogy
11. Moving beyond plain JSON
12. What’s the catch?
13. The Middle Way
14. Client devs love stuff that’s.. 1. Simple & Intuitive 2. Discoverable 3. Reliable
15. “Simplicity”
16. Why simplicity?
17. Simplicity require ‘json’
 require ‘net/http’
 
 # interact with your API
18. The F word
19. The F word FORMS
20. Your hypermedia type doesn’t need forms. But I want dynamic control of UI elements, forms, links, etc..
22. “WebKit in Your Living Room” “Our teams use WebKit, JavaScript, HTML5, and CSS3 to build user interfaces that are delivered to millions of Netflix customers on game consoles, Blu-ray players, and Internet- connected TVs.”
23. Intuitivity {
 _links: {
 self: { href: “/bob” },
 friend: [
 { href: “/ted” },
 { href: “/jen” }
 ]
 },
 date_of_birth: “1970-04-28”,
 favourite_colour: “blue”,
 age: 42,
 …
 }
24. Intuitivity {
 _links: {
 self: { href: “/bob” },
 friend: [
 { href: “/ted” },
 { href: “/jen” }
 ]
 },
 date_of_birth: “1970-04-28”,
 favourite_colour: “blue”,
 age: 42,
 …
 }
25. Intuitivity {
 _links: {
 self: { href: “/bob” },
 friend: [
 { href: “/ted” },
 { href: “/jen” }
 ]
 },
 …
 } {
 _links: [
 { rel: “self”, href: “/bob” },
 { rel: “friend”, href: “/ted” },
 { rel: “friend”, href: “/jen” }
 ],
 …
 }
26. Intuitivity {
 _links: {
 self: { href: “/bob” },
 friend: [
 { href: “/ted” },
 { href: “/jen” }
 ]
 },
 …
 } {
 _links: [
 { rel: “self”, href: “/bob” },
 { rel: “friend”, href: “/ted” },
 { rel: “friend”, href: “/jen” }
 ],
 …
 } _links.friend[0] links.filter(function(link) {
 return link.rel === ”friend”
 })[0]
27. “Discoverability”
28. Discoverability
29. Phased …
30. Phased Disclosure http://t.co/uwNfXpDO
31. 1 2 3 haltalk.herokuapp.com
32. haltalk.herokuapp.com
33. “Reliability”
34. Extension Cool link relations do not break. (but they can change)
35. Versioning (breaking change) Breaking change => new link relation ¤ Granular (no major version changes) ¤ Parallel versions ¤ Deprecation
36. Parallel versioning _links: {
 …
 “v1:widget”: { “href”: “…” },
 “v2:widget”: { “href”: “…” },
 …
 }
37. Deprecation _links: {
 …
 “v1:widget”: { “href”: “…”, “deprecates”: “2012-09-21” },
 …
 }
38. Why use HAL? ¤  ~16 libraries client & server (+more in future) ¤  API Browser (on github) ¤  Battle-tested ¤  bunch of companies using it ¤  ~100 threads & ~200 members on hal-discuss ¤  Extend it J
39. Thanks! Mike Kelly @mikekelly85