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
   

   View Slide

2. Saturday, September 15, 12
   

   View Slide

3. Saturday, September 15, 12
   

   View Slide

4. Saturday, September 15, 12
   

   View Slide

5. REST is
   Saturday, September 15, 12
   

   View Slide

6. Hypermedia APIs
   Saturday, September 15, 12
   

   View Slide

7. Example: Background job that adds two numbers
   Saturday, September 15, 12
   

   View Slide

8. $ 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"}]}}
   Saturday, September 15, 12
   

   View Slide

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: ; rel="profile"
   {“message”: “You are being redirected”}
   Saturday, September 15, 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,
    "status":"in_progress",
    "links":[
    {"href":"/jobs/1",
    "rel":"self"},
    {"href":"/jobs",
    "rel":"index"}]}}
    Saturday, September 15, 12
    

    View Slide

11. $ 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"}]}}
    Saturday, September 15, 12
    

    View Slide

12. WTF?
    Let’s define:
    Saturday, September 15, 12
    

    View Slide

13. Build your API to respect
    the architecture of the web
    Saturday, September 15, 12
    

    View Slide

14. 1: Respect HTTP*
    2: Use a hypermedia type
    Saturday, September 15, 12
    

    View Slide

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
    

    View Slide

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
    

    View Slide

17. Media
    type?
    Saturday, September 15, 12
    

    View Slide

18. A small digression
    (Freed & Borenstein)
    Saturday, September 15, 12
    

    View Slide

19. Link: ; rel="profile"
    Saturday, September 15, 12
    

    View Slide

20. JSON
    API
    (Can’t
    actually
    drive
    your)
    Saturday, September 15, 12
    

    View Slide

21. PROFILE
    Link Relation Type
    Saturday, September 15, 12
    

    View Slide

22. RFC 5988: Web Linking
    Saturday, September 15, 12
    

    View Slide

23. Link: ; rel="profile"
    Saturday, September 15, 12
    

    View Slide

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
    

    View Slide

25. OR...
    Saturday, September 15, 12
    

    View Slide

26. Collection + JSON / HAL
    Saturday, September 15, 12
    

    View Slide

27. Why?
    Saturday, September 15, 12
    

    View Slide

28. Internet:
    BEST THING
    EVAR
    Saturday, September 15, 12
    

    View Slide

29. Web
    Scale
    Saturday, September 15, 12
    

    View Slide

30. Google
    SPDY
    Saturday, September 15, 12
    

    View Slide

31. Saturday, September 15, 12
    

    View Slide

32. Saturday, September 15, 12
    

    View Slide

33. Saturday, September 15, 12
    

    View Slide

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
    

    View Slide

35. “longevity and independent evolution”
    Saturday, September 15, 12
    

    View Slide

36. Saturday, September 15, 12
    

    View Slide

37. Programmers
    are
    hypocrites
    Saturday, September 15, 12
    

    View Slide

38. Node.js is awesome. JS
    everywhere means sharing
    models between client and
    server! - J. Random
    Saturday, September 15, 12
    

    View Slide

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
    

    View Slide

40. SOAP
    COM
    CORBA
    Saturday, September 15, 12
    

    View Slide

41. “distribute your
    objects over the
    network” is an utter
    failure
    Saturday, September 15, 12
    

    View Slide

42. a representation
    metadata that allows them to interpret it
    Saturday, September 15, 12
    

    View Slide

43. a representation
    is data that is structured in some way
    (like application/json)
    Saturday, September 15, 12
    

    View Slide

44. metadata that allows them to interpret it
    is most importantly the media type
    (via Content-Type)
    Saturday, September 15, 12
    

    View Slide

45. Media types provide the rules for
    properly processing a
    representation in that type
    Saturday, September 15, 12
    

    View Slide

46. JSON: RFC4627
    array =
    begin-array
    [ value
    *( value-separator
    value )
    ]
    end-array
    Saturday, September 15, 12
    

    View Slide

47. Media types are
    (dynamic) contracts
    between client and
    server
    Saturday, September 15, 12
    

    View Slide

48. They define the
    processing rules on
    both sides.
    Saturday, September 15, 12
    

    View Slide

49. Client code should be
    processing a media
    type, not duplicating
    business objects.
    Saturday, September 15, 12
    

    View Slide

50. “REST” way: “here’s a
    copy of that object you
    wanted.”
    Saturday, September 15, 12
    

    View Slide

51. Hypermedia way:
    “here’s where you’re at
    in the state machine
    and how to interpret it”
    Saturday, September 15, 12
    

    View Slide

52. State machine?
    Saturday, September 15, 12
    

    View Slide

53. Determinism
    (Laplace’s demon)
    Saturday, September 15, 12
    

    View Slide

54. User interaction can be
    modeled as a state
    machine.
    Saturday, September 15, 12
    

    View Slide

55. API interaction can be
    modeled as a state
    machine.
    Saturday, September 15, 12
    

    View Slide

56. Saturday, September 15, 12
    

    View Slide

57. Saturday, September 15, 12
    

    View Slide

58. Hypermedia links are
    state transitions
    Saturday, September 15, 12
    

    View Slide

59. This is how web
    browsers work.
    Saturday, September 15, 12
    

    View Slide

60. A secret: Web
    browsers are generic
    API clients.
    Saturday, September 15, 12
    

    View Slide

61. Thanks!
    @steveklabnik
    http://desiginghypermediaapis.com
    http://tutorials.jumpstartlab.com
    Saturday, September 15, 12
    

    View Slide