OSCON 2012: Designing Hypermedia APIs

In this talk, Steve will explain how to design your APIs so that they truly embrace the web and HTTP. Just as there's an impedance mismatch between our databases, our ORMs, and our models, there's an equal mismatch between our applications, our APIs, and our clients. Pros and cons of this approach will be discussed, as well as why more people aren't building APIs this way yet.

Transcript

1. Designing Hypermedia APIs by @steveklabnik Wednesday, July 18, 12
2. Wednesday, July 18, 12
3. Wednesday, July 18, 12
4. Wednesday, July 18, 12
5. Hypermedia APIs Wednesday, July 18, 12
6. Example: Background job that adds two numbers Wednesday, July 18, 12
7. $ curl -i -H "Accept: application/json" \ http://localhost:3000 HTTP/1.1 200 OK Link: <http://localhost:3000/profile>; rel="profile" {"job": {"number_one":null, "number_two":null, "links":[ {"href":"/jobs", "rel":"index"}]}} Wednesday, July 18, 12
8. $ curl -i -H "Accept: application/json" \ -X POST \ -d "job[number_one]=1" \ -d "job[number_two]=2" \ http://localhost:3000/jobs HTTP/1.1 302 Found Location: http://localhost:3000/jobs/1 Link: <http://localhost:3000/profile>; rel="profile" {“message”: “You are being redirected”} Wednesday, July 18, 12
9. $ curl -i -H "Accept: application/json" http:// localhost:3000/jobs/1 HTTP/1.1 200 OK Link: <http://localhost:3000/profile>; rel="profile" {"job": {"number_one":1, "number_two":2, "status":"in_progress", "links":[ {"href":"/jobs/1", "rel":"self"}, {"href":"/jobs", "rel":"index"}]}} Wednesday, July 18, 12
10. $ curl -i -H "Accept: application/json" http:// localhost:3000/jobs/1 HTTP/1.1 200 OK Link: <http://localhost:3000/profile>; rel="profile" {"job": {"number_one":1, "number_two":2, "answer":3, "status":"finished", "links":[ {"href":"/jobs/1", "rel":"self"}, {"href":"/jobs", "rel":"index"}]}} Wednesday, July 18, 12
11. WTF? Let’s define: Wednesday, July 18, 12
12. Build your API to respect the architecture of the web Wednesday, July 18, 12
13. Why? Wednesday, July 18, 12
14. Internet: BEST THING EVAR Wednesday, July 18, 12
15. Google SPDY Wednesday, July 18, 12
16. Wednesday, July 18, 12
17. Wednesday, July 18, 12
18. Wednesday, July 18, 12
19. Wednesday, July 18, 12
20. A small digression Wednesday, July 18, 12
21. Structuralism Post-Structuralism Postmodernism Wednesday, July 18, 12
22. Wednesday, July 18, 12
23. W3C and IETF: largest anarchist organizations ever Wednesday, July 18, 12
24. "We reject kings, presidents and voting. We believe in rough consensus and running code." - IETF Credo Wednesday, July 18, 12
25. Wednesday, July 18, 12
26. Back to your regularly scheduled program Wednesday, July 18, 12
27. Cons: 1. Latency 2. Reliance on caching 3. text formats & efficiency Wednesday, July 18, 12
28. Server Side Wednesday, July 18, 12
29. 1: Respect HTTP* 2: Use a hypermedia type Wednesday, July 18, 12
30. • Client-Server • Stateless • Caching • Uniform Interface • identification of resources • representations • self-descriptive messages • hypermedia as the engine of application state • Layered System • Code-on-demand Wednesday, July 18, 12
31. • Client-Server • Stateless • Caching • Uniform Interface • identification of resources • representations • self-descriptive messages • hypermedia as the engine of application state • Layered System • Code-on-demand Wednesday, July 18, 12
32. STOP (only) READING BLOGS!!!!1 Wednesday, July 18, 12
33. 1: Respect HTTP* 2: Use a hypermedia type Wednesday, July 18, 12
34. Media type? Wednesday, July 18, 12
35. Link: <http://localhost:3000/profile>; rel="profile" Wednesday, July 18, 12
36. RFC 5988: Web Linking Wednesday, July 18, 12
37. PROFILE Link Relation Type Wednesday, July 18, 12
38. ... a profile can be described as additional semantics that can be used to process a resource representation, such as constraints, conventions, extensions, or any other aspects that do not alter the basic media type semantics. Wednesday, July 18, 12
39. Link: <http://localhost:3000/profile>; rel="profile" Wednesday, July 18, 12
40. OR... Wednesday, July 18, 12
41. Collection + JSON / HAL Wednesday, July 18, 12
42. Wednesday, July 18, 12
43. Programmers are hypocrites Wednesday, July 18, 12
44. SOAP COM CORBA Wednesday, July 18, 12
45. “distribute your objects over the network” is an utter failure Wednesday, July 18, 12
46. “REST” way: “here’s a copy of that object you wanted.” Wednesday, July 18, 12
47. Hypermedia way: “here’s where you’re at in the state machine and how to interpret it” Wednesday, July 18, 12
48. State Machines Wednesday, July 18, 12
49. Determinism (Laplace’s demon) Wednesday, July 18, 12
50. User interaction can be modeled as a state machine. Wednesday, July 18, 12
51. API interaction can be modeled as a state machine. Wednesday, July 18, 12
52. Wednesday, July 18, 12
53. Wednesday, July 18, 12
54. Hypermedia links are state transitions Wednesday, July 18, 12
55. Media types are (dynamic) contracts between client and server Wednesday, July 18, 12
56. They define the processing rules on both sides. Wednesday, July 18, 12
57. Client Side Wednesday, July 18, 12
58. 1. Implement the media type, not a specific server's responses. 2. If possible, make two services and test your client against both. 3. Be flexible: don't rely on structure too much. 4. Implement local caching. Wednesday, July 18, 12
59. Thanks! @steveklabnik http://hackety.com http://tutorials.jumpstartlab.com Wednesday, July 18, 12