$30 off During Our Annual Pro Sale. View Details »

Designing APIs

Honza Javorek
September 19, 2015

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/

Honza Javorek

September 19, 2015
Tweet

More Decks by Honza Javorek

Other Decks in Technology

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