documenting apis: sample code and more (with many pictures of cats)
DESCRIPTION
A discussion of what makes good API documentation and ways to engage developers through documentation. Presented at API World 2014.TRANSCRIPT
![Page 1: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/1.jpg)
Documenting APIs
with many pictures of cats
![Page 2: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/2.jpg)
Anya StettlerDeveloper Relations
Avalara
anyarms
![Page 3: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/3.jpg)
Why do we need good documentation?
What qualities distinguish “good” documentation?
How can we communicate with developers?
How can we improve existing documentation?
![Page 4: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/4.jpg)
Do we really need API Docs?
YES!
![Page 5: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/5.jpg)
![Page 6: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/6.jpg)
Good documentation is good
• Decreases barriers to entry• Decreases support costs• Works as a marketing tool
![Page 7: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/7.jpg)
![Page 8: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/8.jpg)
zero to “Hello World”
![Page 9: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/9.jpg)
Bad documentation makes your users skeptical …
![Page 10: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/10.jpg)
… or sad.
![Page 11: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/11.jpg)
![Page 12: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/12.jpg)
![Page 13: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/13.jpg)
What is good documentation?
A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.
![Page 14: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/14.jpg)
What is good documentation?
A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.
![Page 15: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/15.jpg)
What is good documentation?
A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.
![Page 16: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/16.jpg)
What is good documentation?
A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.
![Page 17: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/17.jpg)
What is good documentation?
A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.
![Page 18: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/18.jpg)
What is good documentation?
A comprehensive,navigableresource thatprovides users theinformation to builda painless,maintainable,successfulintegration to yourservice.
![Page 19: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/19.jpg)
Types of Docs• Technical Reference• Sample Code/Code Snippets• Tutorials (written, video, interactive)
• Application Samples• Q&A Resources
![Page 20: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/20.jpg)
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
![Page 21: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/21.jpg)
![Page 22: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/22.jpg)
![Page 23: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/23.jpg)
![Page 24: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/24.jpg)
https://dev.twitter.com/rest/reference/post/statuses/update
![Page 25: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/25.jpg)
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
![Page 26: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/26.jpg)
https://stripe.com/docs/api
![Page 27: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/27.jpg)
https://www.twilio.com/docs/api/rest/account
![Page 28: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/28.jpg)
![Page 29: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/29.jpg)
There are tools for this
• Apiary• Mashery I/O docs• Apigee• (and others)
![Page 30: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/30.jpg)
http://docs.themoviedb.apiary.io/
![Page 31: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/31.jpg)
http://developer.klout.com/io-docs
![Page 32: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/32.jpg)
![Page 33: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/33.jpg)
https://apigee.com/console/linkedin
![Page 34: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/34.jpg)
![Page 35: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/35.jpg)
![Page 36: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/36.jpg)
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
![Page 37: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/37.jpg)
http://www.tiobe.com/index.php/content/paperinfo/tpci/index.html
![Page 38: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/38.jpg)
IEEE Spectrum: Top Programming Languages (web)
http://spectrum.ieee.org/static/interactive-the-top-programming-languages#index
![Page 39: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/39.jpg)
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
![Page 40: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/40.jpg)
https://stripe.com/docs/tutorials/charges
![Page 41: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/41.jpg)
https://www.stellar.org/blog/introducing-stellar/
![Page 42: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/42.jpg)
![Page 43: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/43.jpg)
![Page 44: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/44.jpg)
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
![Page 45: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/45.jpg)
https://developers.facebook.com/docs/android/scrumptious/
![Page 46: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/46.jpg)
Q&A resources
• There will still be unanswered questions– Specific use cases– Combinations of resources
• Public answers benefit the community
• Primary values: navigability, simplicity
![Page 47: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/47.jpg)
http://stackoverflow.com/tags
![Page 48: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/48.jpg)
https://developer.salesforce.com/forums/
![Page 49: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/49.jpg)
https://twittercommunity.com/
![Page 50: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/50.jpg)
A comprehensive, navigable resource that provides users the information to build a painless, maintainable, successful integration to your service. • Technical Reference• Sample Code/code snippets• Tutorials (written, video, interactive)
• Application Samples• Q&A resources
![Page 51: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/51.jpg)
Do I really need all those
things?
![Page 52: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/52.jpg)
Top 10 APIsTracked• 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/23http://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
![Page 53: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/53.jpg)
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 yesAmazon 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
![Page 54: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/54.jpg)
Comprehensive vs. Concise?
• Comprehensive– Full coverage for technical references– Common use cases for tutorials/samples
• Length becomes an issue– affects navigation- dilutes understanding- impacts maintenance
![Page 55: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/55.jpg)
Information that isn’t accessible isn’t helpful.
![Page 56: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/56.jpg)
![Page 57: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/57.jpg)
![Page 58: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/58.jpg)
![Page 59: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/59.jpg)
![Page 60: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/60.jpg)
![Page 61: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/61.jpg)
http://developer.avalara.com
![Page 62: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/62.jpg)
http://developer.avalara.com/api-docs/api-reference/rest-curl/gettayes
![Page 63: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/63.jpg)
https://github.com/avadev
![Page 64: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/64.jpg)
![Page 65: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/65.jpg)
So much more!
• SDKs• Developer Blog• Posted Release Notes• Interactive console• Auto-doc tools
![Page 66: Documenting APIs: Sample Code and More (with many pictures of cats)](https://reader038.vdocuments.mx/reader038/viewer/2022103110/547a9e1bb4af9f8b2c8b4678/html5/thumbnails/66.jpg)
but we’re not done yet.
It’s a good start