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
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
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.
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
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