Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Documenting APIs (with many pictures of cats) - APIStrat

699 views

Published on

A discussion of what makes good API documentation and ways to engage developers through documentation. Presented at APIStrat 2014.

Published in: Software
  • Be the first to comment

Documenting APIs (with many pictures of cats) - APIStrat

  1. 1. Documenting APIs with many pictures of cats
  2. 2. Anya Stettler Developer Relations Avalara anyarms
  3. 3. Do we really need API Docs? YES!
  4. 4. Good documentation is good • Decreases barriers to entry • Decreases support costs • Works as a marketing tool
  5. 5. zero to “Hello World”
  6. 6. Bad documentation makes your users skeptical …
  7. 7. … or sad.
  8. 8. Types of Docs • Technical Reference • Sample Code/Code Snippets • Tutorials (written, video, interactive) • Application Samples • Q&A Resources
  9. 9. Technical Reference • Describe everything in your API – Even things you don’t want people to use • Structure should follow the structure of the API – But can intentionally diverge • Primarily values: comprehensive, navigable • Example: Twitter
  10. 10. https://dev.twitter.com/rest/reference/post/statuses/update
  11. 11. Code Snippets • Allow users to learn by example • Demonstrate a single call • Need to be able to copy/paste content – Must work! • Primary values: painless, readability, simplicity • Example: Stripe, Twilio
  12. 12. https://stripe.com/docs/api
  13. 13. https://www.twilio.com/docs/api/rest/account
  14. 14. Which Languages? • At least three languages • At least one raw call/response sample • Two additional samples implies multi-language support • Popularity • Target audience • The more the merrier • as long as they’re maintainable
  15. 15. http://www.tiobe.com/index.php/content/paperinfo/tpci/index.html
  16. 16. IEEE Spectrum: Top Programming Languages (web) http://spectrum.ieee.org/static/interactive-the-top-programming-languages#index
  17. 17. Tutorials • Your product probably has some subtlety – Authorization – Security concerns – Expected workflow • Can take many formats – Step-by-step articles – Videos/screencasts – Interactive consoles • Key Values: successful, painless
  18. 18. https://www.stellar.org/blog/introducing-stellar/
  19. 19. Application Samples • More fully-fledged “learning by example” • Full integration within an application context • Larger samples • More like a POC • Primary values: readability, navigability • Example: Facebook
  20. 20. https://developers.facebook.com/docs/android/scrumptious/
  21. 21. Q&A resources • There will still be unanswered questions – Specific use cases – Combinations of resources • Public answers benefit the community • Primary values: navigability, simplicity
  22. 22. So much more! • SDKs • Developer Blog • Posted Release Notes • Interactive console • Auto-doc tools
  23. 23. Do I really need all those things?
  24. 24. Top 10 APIs Tracked • Facebook • Google Maps • Twitter • YouTube • AccuWeather • LinkedIn • Amazon Product Advertising • Pinterest • Flickr • Google Talk http://www.programmableweb.com/news/most-popular-apis-least-one-will-surprise-you/2014/01/23 http://www.programmableweb.com/category/all/apis?order=field_popularity *As of 2014-09-13 Used • Google Maps • Twitter • YouTube • Flickr • Amazon Product Advertising • Facebook • Twilio • Last.fm • eBay • Twilio SMS
  25. 25. What documentation do they offer? Technical Reference Code Snippets Tutorials Interactive Console SDK Application Samples Q&A Facebook yes yes yes yes yes yes yes Google Maps yes yes yes no yes no stack overflow Twitter yes JSON only yes yes some no yes YouTube yes yes yes yes yes no stack overflow AccuWeather yes no* yes no no no no LinkedIn yes yes yes yes 3rd party no yes Amazon Product Advertising yes 3rd party yes no 3rd party 3rd party yes Pinterest yes no yes no yes no no Flickr yes 3rd party yes yes 3rd party no yes Google Talk** yes yes yes no yes no yes Twilio yes yes yes no yes yes yes Last.fm yes no yes no 3rd party no yes eBay yes yes yes no*** yes yes yes Twilio SMS**** yes yes yes no no no yes * Does provide a JavaScript sample for one resource ** Replaced May 2013, no longer updated *** Has request validator tool **** Deprecated
  26. 26. http://developer.avalara.com
  27. 27. http://developer.avalara.com/api-docs/api-reference/rest-curl/gettax
  28. 28. https://github.com/avadev
  29. 29. Thanks! Anya Stettler Developer Relations Avalara anyarms anya.stettler@avalara.com slides available at http://www.slideshare.net/AnyaStettler

×