OSCON 2012: Designing Hypermedia APIs

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