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
   

   View Slide

2. Wednesday, July 18, 12
   

   View Slide

3. Wednesday, July 18, 12
   

   View Slide

4. Wednesday, July 18, 12
   

   View Slide

5. Hypermedia APIs
   Wednesday, July 18, 12
   

   View Slide

6. Example: Background job that adds two numbers
   Wednesday, July 18, 12
   

   View Slide

7. $ curl -i -H "Accept: application/json" \
   http://localhost:3000
   HTTP/1.1 200 OK
   Link: ;
   rel="profile"
   {"job":
   {"number_one":null,
   "number_two":null,
   "links":[
   {"href":"/jobs",
   "rel":"index"}]}}
   Wednesday, July 18, 12
   

   View Slide

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: ;
   rel="profile"
   {“message”: “You are being redirected”}
   Wednesday, July 18, 12
   

   View Slide

9. $ curl -i -H "Accept: application/json" http://
   localhost:3000/jobs/1
   HTTP/1.1 200 OK
   Link: ; 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
   

   View Slide

10. $ curl -i -H "Accept: application/json" http://
    localhost:3000/jobs/1
    HTTP/1.1 200 OK
    Link: ; 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
    

    View Slide

11. WTF?
    Let’s define:
    Wednesday, July 18, 12
    

    View Slide

12. Build your API to respect
    the architecture of the web
    Wednesday, July 18, 12
    

    View Slide

13. Why?
    Wednesday, July 18, 12
    

    View Slide

14. Internet:
    BEST THING
    EVAR
    Wednesday, July 18, 12
    

    View Slide

15. Google
    SPDY
    Wednesday, July 18, 12
    

    View Slide

16. Wednesday, July 18, 12
    

    View Slide

17. Wednesday, July 18, 12
    

    View Slide

18. Wednesday, July 18, 12
    

    View Slide

19. Wednesday, July 18, 12
    

    View Slide

20. A small digression
    Wednesday, July 18, 12
    

    View Slide

21. Structuralism
    Post-Structuralism
    Postmodernism
    Wednesday, July 18, 12
    

    View Slide

22. Wednesday, July 18, 12
    

    View Slide

23. W3C and IETF:
    largest anarchist
    organizations ever
    Wednesday, July 18, 12
    

    View Slide

24. "We reject kings,
    presidents and voting.
    We believe in rough
    consensus and running
    code." - IETF Credo
    Wednesday, July 18, 12
    

    View Slide

25. Wednesday, July 18, 12
    

    View Slide

26. Back to your regularly scheduled program
    Wednesday, July 18, 12
    

    View Slide

27. Cons:
    1. Latency
    2. Reliance on caching
    3. text formats & efficiency
    Wednesday, July 18, 12
    

    View Slide

28. Server
    Side
    Wednesday, July 18, 12
    

    View Slide

29. 1: Respect HTTP*
    2: Use a hypermedia type
    Wednesday, July 18, 12
    

    View Slide

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
    

    View Slide

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
    

    View Slide

32. STOP (only)
    READING
    BLOGS!!!!1
    Wednesday, July 18, 12
    

    View Slide

33. 1: Respect HTTP*
    2: Use a hypermedia type
    Wednesday, July 18, 12
    

    View Slide

34. Media
    type?
    Wednesday, July 18, 12
    

    View Slide

35. Link: ; rel="profile"
    Wednesday, July 18, 12
    

    View Slide

36. RFC 5988: Web Linking
    Wednesday, July 18, 12
    

    View Slide

37. PROFILE
    Link Relation Type
    Wednesday, July 18, 12
    

    View Slide

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
    

    View Slide

39. Link: ; rel="profile"
    Wednesday, July 18, 12
    

    View Slide

40. OR...
    Wednesday, July 18, 12
    

    View Slide

41. Collection + JSON / HAL
    Wednesday, July 18, 12
    

    View Slide

42. Wednesday, July 18, 12
    

    View Slide

43. Programmers
    are
    hypocrites
    Wednesday, July 18, 12
    

    View Slide

44. SOAP
    COM
    CORBA
    Wednesday, July 18, 12
    

    View Slide

45. “distribute your
    objects over the
    network” is an utter
    failure
    Wednesday, July 18, 12
    

    View Slide

46. “REST” way: “here’s a
    copy of that object you
    wanted.”
    Wednesday, July 18, 12
    

    View Slide

47. Hypermedia way:
    “here’s where you’re at
    in the state machine
    and how to interpret it”
    Wednesday, July 18, 12
    

    View Slide

48. State
    Machines
    Wednesday, July 18, 12
    

    View Slide

49. Determinism
    (Laplace’s demon)
    Wednesday, July 18, 12
    

    View Slide

50. User interaction can be
    modeled as a state
    machine.
    Wednesday, July 18, 12
    

    View Slide

51. API interaction can be
    modeled as a state
    machine.
    Wednesday, July 18, 12
    

    View Slide

52. Wednesday, July 18, 12
    

    View Slide

53. Wednesday, July 18, 12
    

    View Slide

54. Hypermedia links are
    state transitions
    Wednesday, July 18, 12
    

    View Slide

55. Media types are
    (dynamic) contracts
    between client and
    server
    Wednesday, July 18, 12
    

    View Slide

56. They define the
    processing rules on
    both sides.
    Wednesday, July 18, 12
    

    View Slide

57. Client
    Side
    Wednesday, July 18, 12
    

    View Slide

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
    

    View Slide

59. Thanks!
    @steveklabnik
    http://hackety.com
    http://tutorials.jumpstartlab.com
    Wednesday, July 18, 12
    

    View Slide