I Am Hypermedia (And So Can You)

There’s no wrong way to build an API. There are, however, tools and techniques at our disposal for building stable APIs others can depend on without sacrificing our own ability to change. Call it REST, call it Hypermedia, call it anything you like. We’ll keep the examples practical and speak the common languages of HTML and HTTP. This talk is for you if you deploy code to the web even if you’ve never heard of Hypermedia or if you have a life-size poster of Roy Fielding hanging in your office.

Transcript

1. I Am Hypermedia (And So Can You)
2. JSON API
3. > GET /books < 200 OK [{ id: 42, price: "$10.20", title: "The Hitchhiker's Guide..." }, { id: 43, price: "$11.20", title: "The Restaurant at the End..." }] List Books
4. > GET /books?page=2 < 200 OK [{ id: 44, price: "$11.20", title: "So Long, and Thanks for All..." }] List Books
5. View Book Cover > GET /covers/42 < 200 OK < Content-Type: image/png
6. View Book > GET /books/42 < 200 OK { id: 42, price: "$10.20", title: "The Hitchhiker's Guide...", author: "Douglas Adams", owned: false }
7. Purchase Book > POST /purchases { book_id: 42 } < 201 Created { id: 42, price: "$10.20", title: "The Hitchhiker's Guide...", author: "Douglas Adams", owned: true }
8. Read Book > GET /read/42 < 200 OK > GET /read/43 < 403 Forbidden
9. List Purchases > GET /purchases < 200 OK [{ id: 42, price: "$10.20", title: "The Hitchhiker's Guide...", owned: true }]
10. Ship It!
11. Move Images > GET http://cdn.example.com/42.png < 200 OK < Content-Type: image/png > GET /covers/42 < 302 Found < Location: http://cdn.example.com/42.png
12. Lend Book > POST /lendings { book_id: 42, borrower_id: 13 } < 201 Created { id: 42, title: "The Hitchhiker's Guide...", ... }
13. Lend Book > GET /books/42 < 200 OK { id: 42, title: "The Hitchhiker's Guide...", owned: true, lender_id: 13, ... } > GET /read/42 < 200 OK
14. Lend Book > GET /books/42 < 200 OK { id: 42, title: "The Hitchhiker's Guide...", owned: false, borrower_id: 13, ... } > GET /read/42 < 403 Forbidden
15. RPC
16. Hypermedia
17. Hypermedia (a.k.a. REST)
18. “REST emphasizes scalability of component interactions, generality of interfaces, independent deployment of components, and intermediary components to reduce interaction latency, enforce security, and encapsulate legacy systems.” - Roy T. Fielding
19. Media Types
20. H Factors
21. Embedding Links <img src="/covers/42">
22. Outbound Links <a href="/books/42">The Hitchhiker's...</a>
23. Templated Queries <form method="get" action="..."> <input name="query" type="text" value="" /> <input type="submit" value="Search" /> </form>
24. Templated Queries <form method="get" action="/search"> <input name="query" type="text" value="" /> <input type="submit" value="Search" /> </form> GET /search?query=hitchhiker HTTP/1.1 Host: example.org
25. Non-Idempotent Updates <form method="post" action="..."> <input name="tag" type="text" value="" /> <input type="submit" value="Create" /> </form>
26. Non-Idempotent Updates <form method="post" action="/tags"> <input name="tag" type="text" value="" /> <input type="submit" value="Create" /> </form> POST /tags HTTP/1.1 Host: example.org Content-Type: application/x-www-form-urlencoded Content-Length: 29 tag=intergalactic+hitchhiking
27. Idempotent Updates var client = new XMLHttpRequest(); client.open("DELETE", "/tags/" + id); client.send();
28. Read Controls <x:include href="http://example.org/feed" accept="application/rss" />
29. Update Controls <form method="post" action="..." enctype="multipart/form-data">
30. Method Controls <form method="post" action="...">
31. Link Semantics <a rel="next" href="...">Next</a> <link rel="stylesheet" href="..." />
32. H Factors LE: Embedding links LO: Outbound links LT: Templated queries LN: Non-Idempotent updates LI: Idempotent updates CR: Read control data CU: Update control data CM: Request control data CL: Link control data
33. Hypermedia API
34. > GET / < 200 OK <a rel="books" href="...">Books</a> <a rel="purchases" href="...">Purchases</a> List Books
35. => books < 200 OK <ol id="books"> <li> <span class="price">$10.20</span> <a rel="self" class="name" href="..."> The Hitchhiker's Guide... </a> </li> <li> ... </li> </ol> <a rel="next" href="...">Next</a> List Books
36. List Books => next < 200 OK <ol id="books"> <li> <span class="price">$11.20</span> <a rel="self" class="name" href="..."> So Long, and Thanks for All... </a> </li> </ol> <a rel="prev" href="...">Prev</a>
37. View Book => self < 200 OK <img src="..."> <span class="price">$11.20</span> <span class="name">The Hitchhiker's...</span> <span class="author">Douglas Adams</span> <form method="post" action="..."> <input name="book_id" value="42"> <input type="submit" value="Buy"> </form>
38. Purchase Book => submit form < 201 Created <img src="..."> <span class="price">$11.20</span> <span class="name">The Hitchhiker's...</span> <span class="author">Douglas Adams</span> <a rel="read" href="...">Read</a> => read < 200 OK
39. List Purchases > GET / < 200 OK <a rel="books" href="...">Books</a> <a rel="purchases" href="...">Purchases</a> => purchases < 200 OK <ol id="books"> <li> ... </li> </ol>
40. Ship It!
41. Move Images => self < 200 OK <img src="/covers/42"> => self < 200 OK <img src="http://cdn.example.com/42.png">
42. Lend Book => self < 200 OK <img src="..."> <span class="price">$11.20</span> <span class="name">The Hitchhiker's...</span> <span class="author">Douglas Adams</span> <a rel="read" href="...">Read</a> <form method="post" action="..."> <input name="book_id" value="42"> <input name="borrower_id" value=""> <input type="submit" value="Lend"> </form>
43. Lend Book => submit form < 201 Created <img src="..."> <span class="price">$11.20</span> <span class="name">The Hitchhiker's...</span> <span class="author">Douglas Adams</span>
44. Lend Book => self < 200 OK <img src="..."> <span class="price">$11.20</span> <span class="name">The Hitchhiker's...</span> <span class="author">Douglas Adams</span> <a rel="read" href="...">Read</a> <form method="post" action="..."> <input name="book_id" value="42"> <input type="submit" value="Buy"> </form>
45. Hypermedia or RPC?
46. I Am Hypermedia (And So Can You) Sources: https://gist.github.com/3962445