Designing APIs

PUT or POST? How should I design URLs? How should I version my API? How to PATCH my JSON? How to validate? I’ll try to answer questions like this, either by explaining the best practices or pointing you to couple of valuable resources. Moreover, I will try to also show you that all this is rather API craft than API design. Future brings the real challenges: use­case oriented interfaces, evolvable servers, adaptable clients. No more deprecated API versions, broken client apps and frustrated client developers!

http://webexpo.net/prague2015/talk/designing-apis-mastering-http-is-just-beginning/

Transcript

1. Designing
   APIs
   @honzajavorek
   honzajavorek.cz
   Honza Javorek
   apiary.io
   

   View Slide

2. Day Night
   apiary.io
   Czech Python
   Community Mascot
   python.cz
   Spaghetti Code
   Hunter
   

   View Slide

3. how does the Ideal
   WEB API look like?
   Designing APIs...
   

   View Slide

4. use HTTP verbs: PUT, POST, DELETE!
   nouns in plural, not verbs!
   use 4xx error codes!
   use media types!
   provide filtering, sorting, pagination!
   versioning! JSON!
   CRUD × use cases!
   do not just expose database tables as resources!
   pretty URLs!
   

   View Slide

5. HmM...
   no.
   

   View Slide

6. backward compatible
   perfectly documented
   available
   exposes enough to satisfy my use case
   easy to learn
   consistent
   easy to use
   

   View Slide

7. DX
   Architecture
   Protocol
   

   View Slide

8. DX
   Architecture
   Protocol
   {
   {
   good framework
   could do for you
   ART
   ×
   CRAFT
   can't
   be automated
   

   View Slide

9. DX
   Architecture
   Protocol
   {
   {
   good framework
   could do for you
   can't
   be automated
   }API builders
   see just this
   

   View Slide

10. protocol
    

    View Slide

11. Architecture
    

    View Slide

12. DEVELOPER
    EXPERIENCE
    . . .
    

    View Slide

13. don't forget there are
    people, not machines
    

    View Slide

14. "One should not treat others in ways
    that one would not like to be treated."
    (the ethic of reciprocity)
    

    View Slide

15. Errors
    Learn how to properly do error responses and messages.
    github.com/blongden/vnd.error
    Documentation
    - make sure it is up to date (test it!)
    - provide the big picture (not just reference)
    Consistency
    - make decisions, and then stick to them
    

    View Slide

16. Errors
    Learn how to properly do error responses and messages.
    github.com/blongden/vnd.error
    Documentation
    - make sure it is up to date (test it!)
    - provide the big picture (not just reference)
    Consistency
    - make decisions, and then stick to them
    Dredd
    github.com/apiaryio/dredd
    Apiary
    

    View Slide

17. ARCHITECTURE
    . . .
    

    View Slide

18. DB
    ×
    api
    DOMAIN LOGIC
    API
    AFFORDANCE
    AFFORDANCE
    X
    

    View Slide

19. AFFORDANCES
    beer example idea by Stephen Mizell
    Empty state
    Drink? No.
    Add beer? Yes.
    Complain? Yes.
    Half full state
    Drink? Yes.
    Add beer? Yes.
    Complain? Yes.
    Full state
    Drink? Yes.
    Add beer? No.
    Complain? No.
    Resource: a beer glass
    

    View Slide

20. Finite state
    machine
    

    View Slide

21. Finite state
    machine
    beer example idea by Stephen Mizell
    

    View Slide

22. REPRESENTATION of
    STATE in HTTP?
    

    View Slide

23. REPRESENTATION of
    STATE in HTTP?
    easy: the JSON document you send back and forth
    Representing state of the beer glass:
    {"fullness": 50}
    

    View Slide

24. BUT HOW TO REPRESENT
    TRANSITIONS IN HTTP?
    ?
    ? ?
    ?
    ?
    ?
    ?
    ?
    ?
    

    View Slide

25. TRANSITIONS IN HTTP
    ?
    ? ?
    ?
    ?
    ?
    ?
    ?
    ?
    

    View Slide

26. HYPERLINK
    since 1965
    

    View Slide

27. WEB
    A P I
    

    View Slide

28. View Slide

29. EVOL
    V
    ABLE
    Decoupled! No hardcoded URLs.
    Clients follow links and adapt to what is available.
    

    View Slide

30. Removed an edit link? Clients won't break.
    1 request instead of 100? Clients won't break.
    Design of URLs? Doesn't matter.
    Versioning? No, sorry.
    

    View Slide

31. View Slide

32. DESIGNING AN API?
    1. model your domain logic, semantic model
    (focus on resources, use cases, affordances)
    2. draw a finite state machine
    3. choose a suitable format (HTML, HAL, Siren, …)
    4. explain your semantics (write a "profile")
    5. build the API, build smart API clients
    

    View Slide

33. DESIGNING AN API?
    1. model your domain logic, semantic model
    (focus on resources, use cases, affordances)
    2. draw a finite state machine
    3. choose a suitable hypermedia type (HAL, Siren, …)
    4. explain your semantics (write a "profile")
    5. build the API, build smart API clients
    Apiary
    Hyperdrive
    github.com/the-hypermedia-project/Hyperdrive
    API Blueprint, MSON
    apiblueprint.org, github.com/apiaryio/mson
    

    View Slide

34. THE WEB
    the most scalable and robust architecture
    humanity invented so far
    

    View Slide

35. REST
    OH, and by the w
    aY, this
    architectural style is called...
    

    View Slide

36. REST
    OH, and by the w
    aY, this
    architectural style is called...
    pro tip: when searching the web,
    look for hypermedia instead
    

    View Slide

37. IT's not a sil
    ver
    bullet
    as any other architectural style,
    REST has benefits and tradeoffs
    

    View Slide

38. "If you think you have control over the
    system or aren't interested in
    evolvability, don't waste your time
    arguing about REST."
    —— Roy T. Fielding
    http:/
    /www.slideshare.net/royfielding/rest-in-aem
    

    View Slide

39. View Slide

40. View Slide

41. PROTOCOL
    . . .
    

    View Slide

42. HTTP
    

    View Slide

43. RTFM
    

    View Slide

44. Everything important is in RFCs.
    Do not rely on blog articles, read the specs.
    No fear! RFCs are human-readable text!
    Use API frameworks to do the heavy lifting.
    Do not miss RFCs 2324 and 7168
    

    View Slide

45. SO THE TEASER w
    as
    A SCAM?
    RFC 7231
    section 4.1
    RFC 5789
    RFC 6902
    RFC 7386
    Please, do not
    begin with
    mastering HTTP!
    You should not.
    json-schema.org
    (…yes, it was!)
    

    View Slide

46. THANK YOU
    DX
    Architecture
    Protocol
    DX
    Architecture
    Protocol
    Your web API
    before this talk
    Your web API
    after this talk
    

    View Slide