Designing Hypermedia APIs - RailsClub2012

This is my hypermedia talk I gave at RailsClub 2012

Transcript

1. Designing Hypermedia APIs by @steveklabnik Saturday, September 15, 12
2. Saturday, September 15, 12
3. Saturday, September 15, 12
4. Saturday, September 15, 12
5. REST is Saturday, September 15, 12
6. Hypermedia APIs Saturday, September 15, 12
7. Example: Background job that adds two numbers Saturday, September 15, 12
8. $ 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"}]}} Saturday, September 15, 12
9. $ 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”} Saturday, September 15, 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, "status":"in_progress", "links":[ {"href":"/jobs/1", "rel":"self"}, {"href":"/jobs", "rel":"index"}]}} Saturday, September 15, 12
11. $ 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"}]}} Saturday, September 15, 12
12. WTF? Let’s define: Saturday, September 15, 12
13. Build your API to respect the architecture of the web Saturday, September 15, 12
14. 1: Respect HTTP* 2: Use a hypermedia type Saturday, September 15, 12
15. • 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 Saturday, September 15, 12
16. • 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 Saturday, September 15, 12
17. Media type? Saturday, September 15, 12
18. A small digression (Freed & Borenstein) Saturday, September 15, 12
19. Link: <http://localhost:3000/profile>; rel="profile" Saturday, September 15, 12
20. JSON API (Can’t actually drive your) Saturday, September 15, 12
21. PROFILE Link Relation Type Saturday, September 15, 12
22. RFC 5988: Web Linking Saturday, September 15, 12
23. Link: <http://localhost:3000/profile>; rel="profile" Saturday, September 15, 12
24. ... 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. Saturday, September 15, 12
25. OR... Saturday, September 15, 12
26. Collection + JSON / HAL Saturday, September 15, 12
27. Why? Saturday, September 15, 12
28. Internet: BEST THING EVAR Saturday, September 15, 12
29. Web Scale Saturday, September 15, 12
30. Google SPDY Saturday, September 15, 12
31. Saturday, September 15, 12
32. Saturday, September 15, 12
33. Saturday, September 15, 12
34. "REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. Many of the constraints are directly opposed to short-term efficiency. Unfortunately, people are fairly good at short- term design, and usually awful at long-term design." - Fielding Saturday, September 15, 12
35. “longevity and independent evolution” Saturday, September 15, 12
36. Saturday, September 15, 12
37. Programmers are hypocrites Saturday, September 15, 12
38. Node.js is awesome. JS everywhere means sharing models between client and server! - J. Random Saturday, September 15, 12
39. $ tree -d src /home/steveklabnik/src |-- my_rails_app | `-- app | `-- models | `-- foo.rb |-- my_api_gem `-- lib `-- my_api_gem `-- foo.rb Saturday, September 15, 12
40. SOAP COM CORBA Saturday, September 15, 12
41. “distribute your objects over the network” is an utter failure Saturday, September 15, 12
42. a representation metadata that allows them to interpret it Saturday, September 15, 12
43. a representation is data that is structured in some way (like application/json) Saturday, September 15, 12
44. metadata that allows them to interpret it is most importantly the media type (via Content-Type) Saturday, September 15, 12
45. Media types provide the rules for properly processing a representation in that type Saturday, September 15, 12
46. JSON: RFC4627 array = begin-array [ value *( value-separator value ) ] end-array Saturday, September 15, 12
47. Media types are (dynamic) contracts between client and server Saturday, September 15, 12
48. They define the processing rules on both sides. Saturday, September 15, 12
49. Client code should be processing a media type, not duplicating business objects. Saturday, September 15, 12
50. “REST” way: “here’s a copy of that object you wanted.” Saturday, September 15, 12
51. Hypermedia way: “here’s where you’re at in the state machine and how to interpret it” Saturday, September 15, 12
52. State machine? Saturday, September 15, 12
53. Determinism (Laplace’s demon) Saturday, September 15, 12
54. User interaction can be modeled as a state machine. Saturday, September 15, 12
55. API interaction can be modeled as a state machine. Saturday, September 15, 12
56. Saturday, September 15, 12
57. Saturday, September 15, 12
58. Hypermedia links are state transitions Saturday, September 15, 12
59. This is how web browsers work. Saturday, September 15, 12
60. A secret: Web browsers are generic API clients. Saturday, September 15, 12
61. Thanks! @steveklabnik http://desiginghypermediaapis.com http://tutorials.jumpstartlab.com Saturday, September 15, 12