Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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. 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!
  2. DX Architecture Protocol { { good framework could do for

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

    you can't be automated }API builders see just this
  4. "One should not treat others in ways that one would

    not like to be treated." (the ethic of reciprocity)
  5. 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
  6. 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
  7. 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
  8. REPRESENTATION of STATE in HTTP? easy: the JSON document you

    send back and forth Representing state of the beer glass: {"fullness": 50}
  9. 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.
  10. 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
  11. 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
  12. REST OH, and by the w aY, this architectural style

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

    style, REST has benefits and tradeoffs
  14. "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
  15. 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
  16. 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!)
  17. THANK YOU DX Architecture Protocol DX Architecture Protocol Your web

    API before this talk Your web API after this talk