1. Survival Strategies for API Documentation By Tom Johnson www.idratherbewriting.com May 7, 2015 East Bay STC 2. "Complete and accurate documentation" is most important factor in APIs, according to a survey by @programmableweb. 250 respondents. http://bit.ly/progwebsurvey Important factors in API doc 3. Presentation by John Musser, founder of programmableweb.com, which has directory of 12,000+ APIs. http://bit.ly/jmusserslideshare 4. Flickr http://bit.ly/ZFYI0T 5. Says, The client wants to find someone who'll emulate Dropbox's developer documentation 6. Docs are how users navigate an API product. With APIs, docs are the interface 7. More info needed Download for free at http://bit.ly/stcintercoma piissue 8. About me Started doing API/SDK documentation 2+ years ago. Am still learning a ton, but enjoy this type of documentation a lot. English major / writing background. Not a programmer, but I do like code. Blog and podcast at idratherbewriting.com 9. Some basics about the API landscape System B System A An API is an interface. Lots of different types of APIs for example: Platform APIs REST APIs Flickr: http://bit.ly/1DexWM0 10. SDK versus API API (application programming interface): Endpoints, classes, or other functions. SDK (software development kit): Implementation tooling to support the API. 11. At least two deliverables API Reference User Guides 12. Outline 1. Platform APIs 2. REST APIs 3. API documentation survey 4. API doc publishing trends 5. Questions to consider 13. DEEP DIVE INTO PLATFORM APIS 14. Auto-doc with Platform APIs /** * Reverses the order of the elements in the specified list.

* * This method runs in linear time. * * * @param list the list whose elements are to be reversed. * @throws UnsupportedOperationException if the specified list or * its list-iterator does not support the set operation. */ public static void reverse(List list) { int size = list.size() if (size < REVERSE_THRESHOLD || list instanceof RandomAccess) { for (int i=0, mid=size>>1, j=size-1; i Developer > JavaScript Console. 2. Now go to http://idratherbewriting.com/wp- content/apidemos/eventbrite.html. 3. Expand the description and name sections in the payload logged to the console. 41. Common sections in REST API doc Endpoint Description Parameters Methods Success response Error response Sample call Cover these details for each resource in your REST API docs. Click thumbnail for example. 42. Flickr Example: Get gallery photos 43. Get flickr photo gallery Endpoint: flickr.galleries.getPhotos Endpoint with values: https://api.flickr.com/services/rest/?method=fl ickr.galleries.getPhotos&api_key=c962d7440cbbf3 81785c09989ba8032e&gallery_id=66911286- 72157647277042064&format=json&nojsoncallback=1 Response: { "score": 92.2655186160279, "scoreDelta": { "dayChange": 0.00044535591406713593, } 44. Activity: Explore payload values 1. With the JavaScript Console open, go to http://idratherbewriting.com/wp- content/apidemos/flickr.html. 2. Inspect the payload logged to the console. 3. Try to find the image source URLs. 4. View the source code of the page to see how the image URLs are constructed. 45. $("#flickr").append(''); API reference docs dont tell you how to actually do a real task. To construct the img URL, you need to combine 4 different parts from the response. 46. Flickr Result 47. More details on the API calls Go here for details: http://bit.ly/restapiexamples 48. Recommended Resource http://bit.ly/docrestapis 49. API DOCUMENTATION SURVEY 50. Types of APIs that writers document 0% 10% 20% 30% 40% 50% 60% 70% 80% 90% 51. Are you automating REST API docs? No Yes N/A 0% 10% 20% 30% 40% 50% 60% 70% Percent 52. Authoring tools used by API doc writers 0 10 20 30 40 50 60 70 80 53. Do you test out the API calls used in your doc yourself? Yes No Sometimes 0% 10% 20% 30% 40% 50% 60% 54. What IDE do you use? Eclipse None Visual Studio IntelliJ IDEA Xcode Other 0% 5% 10% 15% 20% 25% 30% 35% 40% 45% 50% 55. Most common programming languages tech writers know 0 5 10 15 20 25 56. Do developers write the initial API documentation in the source code? Yes No Sometimes 28% 29% 30% 31% 32% 33% 34% 35% 36% 37% 57. Do you write doc by looking in the source code? Yes No 0% 10% 20% 30% 40% 50% 60% 70% 58. How do you access the source code? Git Perforce No access to code SVN Other Mercurial 0% 5% 10% 15% 20% 25% 30% 35% 40% 59. Most difficult part of API doc? Understand code Get info from engineers Create non-ref docs Understand audience Identify dependencies 0% 5% 10% 15% 20% 25% 30% 35% 40% 45% 50% Percent 60. How did you learn what you needed to know? 0% 5% 10% 15% 20% 25% 30% 35% 40% 45% 50% 61. PUBLISHING TRENDS WITH APIS 62. Programmableweb.com: API Directory 12,000 + web APIs 63. What design trends or patterns do we see among popular API doc sites? Flickr: http://bit.ly/1sWdnln 64. Yelp API One seamless website matching product branding. http://www.yelp.com/developers/documentation 65. Twilio API One output, with nav tabs to show different languages 66. Twitter API Interactive, real- time requests based on your auth key 67. Dynamically inserted API keys into code samples. https://stripe.com/docs/api 68. Foursquare API Getting Started section, providing a sample Hello World tutorial https://developer.foursquare.com/start 69. Youtube API Lots of code samples, usually with syntax highlighting and surrounding commentary. https://developers.google.com/youtube/v3/code_samples/apps-script 70. Single page scroll w/ TOC highlight Third column to show responses or code samples. http://crimson-cormorant.cloudvent.net/ 71. Jekyll API doc theme from CloudCannon 72. Automating API docs Swagger: 600+ repos RAML: 180+ repos API Blueprint: 120+ repos slide notes from Jennifer Rondeau presentation on REST API Doc 73. Use Swagger Editor to create YML file for Swagger http://editor.swagger.io/#/edit Swagger is just a standard way of describing your API using a particular schema. 74. Swagger UIs output http://petstore.swagger.wordnik.com/ 75. QUESTIONS TO CONSIDER 76. Big questions to answer Am I technical enough to excel in API documentation? 77. Big questions to answer Is API documentation dry and boring? 78. Big questions to answer How do I get into API documentation in the first place? 79. Tom Johnson http://idratherbewriting.com @tomjohnson