Designing APIs

7b2e4bf7ecca28e530e1c421f0676c0b?s=47 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/

7b2e4bf7ecca28e530e1c421f0676c0b?s=128

Honza Javorek

September 19, 2015
Tweet

Transcript

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

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

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

  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!
  5. HmM... no.

  6. backward compatible perfectly documented available exposes enough to satisfy my

    use case easy to learn consistent easy to use
  7. DX Architecture Protocol

  8. DX Architecture Protocol { { good framework could do for

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

    you can't be automated }API builders see just this
  10. protocol

  11. Architecture

  12. DEVELOPER EXPERIENCE . . .

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

  14. "One should not treat others in ways that one would

    not like to be treated." (the ethic of reciprocity)
  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
  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
  17. ARCHITECTURE . . .

  18. DB × api DOMAIN LOGIC API AFFORDANCE AFFORDANCE X

  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
  20. Finite state machine

  21. Finite state machine beer example idea by Stephen Mizell

  22. REPRESENTATION of STATE in HTTP?

  23. REPRESENTATION of STATE in HTTP? easy: the JSON document you

    send back and forth Representing state of the beer glass: {"fullness": 50}
  24. BUT HOW TO REPRESENT TRANSITIONS IN HTTP? ? ? ?

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

    ? ?
  26. HYPERLINK since 1965

  27. WEB A P I

  28. None
  29. EVOL V ABLE Decoupled! No hardcoded URLs. Clients follow links

    and adapt to what is available.
  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.
  31. None
  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
  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
  34. THE WEB the most scalable and robust architecture humanity invented

    so far
  35. REST OH, and by the w aY, this architectural style

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

    is called... pro tip: when searching the web, look for hypermedia instead
  37. IT's not a sil ver bullet as any other architectural

    style, REST has benefits and tradeoffs
  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
  39. None
  40. None
  41. PROTOCOL . . .

  42. HTTP

  43. RTFM

  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
  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!)
  46. THANK YOU DX Architecture Protocol DX Architecture Protocol Your web

    API before this talk Your web API after this talk