Client-centric API development

How you should develop your API to bring joy to your users instead of tears and sorrow.

Transcript

1. @almadcz, @apiaryio Lukas Linhart CLIENT-CENTRIC API DEVELOPMENT Hi, I am Lukas @almadcz and I work for http://apiary.io.
2. We want API providers to stop inflicting pain on API consumers
3. Fancy way of exposing your database table. This is *not* a good design !
4. let me tell you why we do things, what keeps us up at night
5. You shouldn’t be egoistic and only look at your model of the world
6. CLIENT-CENTRIC Good API starts with good questions. How is your api going to be used?
7. It’s same as building business: find users/customers, validate & iterate.
8. You are going to find out about their culture.
9. You may find a quicky clients, but you should know what they want before saying no.
10. EXPRESSING INTENT Just write it as you would ask them in an e-mail, only with small markdown annotations (actually API Blueprint, http://apiblueprint.org/)
11. USER TESTING This blueprint (via apiary.io) gives you mock server, so you can foce your client to start developing.
12. Now you both can make prorotype—not only of API, but of the client application. That’s where the dragons lie: in user interaction. That’s where you going to find out about missing fields, bad resources…
13. …and you can iterate. Independently, having versioned text-file to talk in, and playing with the design (every client may even have multiple mock versions, sending pull-request after their idea is verified).
14. TDD/BDD DONE RIGHT • Usage of the (web) API first • intent - test (serving as documentation) - implement - watch for regressions • …documentation (serving as a test) The point of TDD is not to have test. The point is to think about what the given method should do and how it’s best invoked / used. ! This is the same on API level.
15. DREDD As for the last phase, dredd is a tool to verify blueprint is in sync with your implementation. Put this into your CI!
16. Start today and do baby steps. You don’t introduce tests into big project by big 100% coverage testing project— you start by covering the things you develop and refactor. ! Start doing this to your API now.
17. E-MAIL lukas@apiary.io TWITTER @apiaryio @apiblueprint Q&A
18. Photo Credit: <a href="http://www.flickr.com/photos/48266396@N00/254910627/">victoriapeckham</a> via <a href="http://compfight.com">Compfight</a> <a href=“https://creativecommons.org/licenses/by/2.0/">cc</a> Photo Credit: <a href="http://www.flickr.com/photos/78147607@N00/2246981042/">euthman</a> via <a href="http://compfight.com">Compfight</a> <a href=“https://creativecommons.org/licenses/by/2.0/">cc</a> Photo Credit: <a href="http://www.flickr.com/photos/68027238@N05/8031424345/">AGraddyPhoto</a> via <a href="http://compfight.com">Compfight</a> <a href=“https://creativecommons.org/licenses/by-nd/2.0/“>cc</a> Photo Credit: <a href="http://www.flickr.com/photos/22206521@N03/2200500024/">Colin_K</a> via <a href="http://compfight.com">Compfight</a> <a href=“https://creativecommons.org/licenses/by/2.0/">cc</a> Photo Credit: <a href="http://www.flickr.com/photos/80384851@N00/9215162641/">loop_oh</a> via <a href="http://compfight.com">Compfight</a> <a href=“https://creativecommons.org/licenses/by-nd/2.0/">cc</a> Photo Credit: <a href="http://www.flickr.com/photos/89228431@N06/11220931254/">reynermedia</a> via <a href="http://compfight.com">Compfight</a> <a href=“https://creativecommons.org/licenses/by/2.0/">cc</a> Photo Credit: <a href="http://www.flickr.com/photos/80497449@N04/8691983876/">Free Grunge Textures - www.freestock.ca</a> via <a href="http://compfight.com">Compfight</a> <a href=“https://creativecommons.org/licenses/by/2.0/">cc</a> http://www.flickr.com/photos/raindrift/7095243379/in/set-72157629492908038 Photo Credit: <a href="http://www.flickr.com/photos/41463627@N05/5385576298/">josemanuelerre</a> via <a href="http://compfight.com">Compfight</a> <a href="https://creativecommons.org/licenses/by-nd/2.0/">cc</a> Photo Credit: <a href="http://www.flickr.com/photos/9361468@N05/2765597758/">quapan</a> via <a href="http://compfight.com">Compfight</a> <a href="https://creativecommons.org/licenses/by/2.0/">cc</a> CREDITS