survival strategies for api documentation: presentation to southwestern ontario stc chapter
TRANSCRIPT
Survival Strategies for API Documentation
By Tom Johnson
www.idratherbewriting.com
Feb 2, 2015
Southwestern Ontario STC Chapter Webinar
"Complete and accurate documentation" is most important factor in APIs, according to a survey by @programmableweb. 250 respondents.
Important factors in API doc
Presentation by John Musser, founder of programmableweb.com,which has directory of 12,000+ APIs
Says, “The client wants to find someone who'll emulate
Dropbox's developer documentation”
Docs are how users navigate an API product.
With APIs, docs are the interface
More info
needed
About me
• Started doing API/SDK documentation a couple of 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
Disclaimer: There’s a lot of things I simply do not know.
Some basics about the API landscape
System BSystem A
An API is an interface between two systems.
Lots of different types of APIs – for example:
1. Platform APIs that you download and add to your project before compiling.
2. REST APIs that you access through HTTP web requests.
SDK versus API
• API (application programming interface): An interface that provides endpoints, classes, or other functions.
• SDK (software development kit): A set of implementation tools to make it easier to work with an API.
SDK example: A JavaScript SDK that allows you to work with a particular REST API using JavaScript syntax as your implementation format.
Reference and User Guides
API docs usually have at least two deliverables.
Auto-doc with Platform APIs/**
* Reverses the order of the elements in the specified list.<p>
*
* 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 <tt>set</tt>
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<mid;
i++, j--)
swap(list, i, j);
} else {
…
Add documentation in the source code, structuring it with specific syntax that a documentation generator can read.
Comments get rendered into Javadoc
- Commonly used.- Works only for Java.- Run it from your IDE.- Automate into builds.- Explore other doclets.- Has frame-based -output.- Can skin with CSS.- Looks professional.
Doxygen
- Commonly used.- Works with Java, C++, C#, and others.- Has easy front-end GUI.- Point it at your source files.- Automate into builds.- Can include non-source files (Markdown).- Frame-based output.- Skinnable.
Good example of source-gen. doc
https://www.dropbox.com/developers/coreEach language uses a doc generator for that language.
https://www.dropbox.com/developers/core
Pros of in-source documentation
- Avoids documentation drift
- Allows the person who creates the code (and so best understands it) to also document it
- Includes tooltips when others incorporate the library into their projects- Integrates into developer’s IDE
Doc
SrcDoc Src
Continental drift
Pros/cons with Platform APIs
ProsPerformance: Performance is faster. (REST APIs struggle with latency for web calls.)
Security: More secure.
ConsLanguage coverage: Harder for devs to create APIs for each language (C++, Java, etc.). As prog. languages proliferate, it’s harder to keep up.
Upgrades: Once clients install, it’s hard to encourage upgrades to latest versions.
REST API basics
URLs requests return specific data HTTP Request
Re
spo
nse
Responses in JSON or XML
Configuration parameters
Re
spo
nse
in J
SON
fo
rmat
Add parameters to endpoints
https://api.flickr.com/services/rest/?method=flickr.activity.userPhotos&api_key=1712c56e30dbad5ef736245cda0d1cb9&per_page=10&format=json&nojsoncallback=1
Knowing what parameters you can include with an endpoint is a huge part of the REST API documentation.
cURL calls
HTTP requests are often demonstrated through cURL calls, with different HTTP methods:
GET – retrievePOST – editPUT – createDELETE – remove
You can use a command line to pass cURL calls, and you can specify different HTTP methods.
Many sample REST calls are demonstrated in cURL.
Flickr Example: Get gallery photos
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
81785c09999ba8032e&gallery_id=66911286-
72157647277042064&format=json&nojsoncallback=1
Response:
{
"score": 92.2655186160279,
"scoreDelta": {
"dayChange": 0.00044535591406713593,
… }
Flickr Response
$("#flickr").append('<img src="https://farm' +
farmId + '.staticflickr.com/' + serverId + '/'
+ id + '_' + secret + '.jpg"/>');
API reference docs don’t tell you how to actually do
a real task. To construct the img URL, you need to combine 4 different parts
from the response.
Flickr Result
More details on the API callsGo here for details: http://bit.ly/restapiexamples
Convert your help into an API
The Jekyll Pages API plugin
converts your Jekyll pages into a
JSON file.
http://idratherbewriting.com/wp-content/apidemos/docasapi/api/v1/pages.json
Call the API<script>
var url = "http://idratherbewriting.com/wp-content/apidemos/docasapi/api/v1/pages.json";
$.getJSON(url, function(data) {
console.log(data);
$.each(data.entries, function(i, page) {
if (page.url == "/wp-content/apidemos/docasapi/mynameistom/") {
$("#tomsmyname").append(page.body);
}
});
});
</script>
<div id="tomsmyname"></div>
Sample Responses
http://idratherbewriting.com/wp-content/apidemos/sampledocapicall.html
More details
http://bit.ly/jekylljsonapi
With REST APIs, auto-doc not as common b/c source lang. varies
“The beauty of Web APIs is that they can be written in whatever language you like and in whatever manner you like. As long as when an HTTP request comes in, the proper HTTP response goes out, it doesn't matter how it actually happens on the server. But this very flexibility makes automated documentation nearly impossible, since there's no standard mapping between what an API request is and what the code is that generates its response.”-- Kin Lane, APIevangelist.com
Autodoc possibility: Swagger spec
RAML (REST API modeling language)
Swagger UI can parse the Swagger syntax and render an output
Generates an endpoint based on values you enter
Mashery with Klout
Doc becomes interactive when you’re signed in.
htt
p:/
/dev
elo
per
.klo
ut.
com
/io
-do
cs
Mashery.io
This is an API for USA Today. The Swagger and RAML parsers essentially create an API explorer experience with some doc mixed in.
http://developer.usatoday.com/io-docs
Swagger spec can be in source code or in separate YML file
• Swagger spec syntax can be separate yml file or integrated in code using a specific Swagger library
• Swagger has various libraries for different languages.
• Swagger spec is different from Swagger UI
• RAML is a competing spec to Swagger
Information survey on my blog
• 42 respondents working in API documentation
• Many people polled from API Documentation group on Linkedin + blogosphere
Types of APIs that writers document
0%
10%
20%
30%
40%
50%
60%
70%
80%
90%
Are you automating REST API docs?
No Yes N/A
0%
10%
20%
30%
40%
50%
60%
70%
Percent
How are you automating REST API docs?
• - custom scripts• - custom tooling• - homegrown framework• - homegrown Python scripts• - custom tooling• - Swagger• - Swagger• - Swagger• - Corilla.co• - code responses auto-generated• - some code samples auto-generated
Authoring tools used by API doc writers
0
10
20
30
40
50
60
70
80
Do you test out the API calls used in your doc yourself?
Yes No Sometimes
0%
10%
20%
30%
40%
50%
60%
What IDE do you use?
Eclipse None Visual Studio IntelliJ IDEA Xcode Other
0%
5%
10%
15%
20%
25%
30%
35%
40%
45%
50%
Most common programming languages tech writers know
0
5
10
15
20
25
Do developers write the initial API documentation in the source code?
Yes No Sometimes
28%
29%
30%
31%
32%
33%
34%
35%
36%
37%
Do you write doc by looking in the source code?
Yes No
0%
10%
20%
30%
40%
50%
60%
70%
How do you access the source code?
Git Perforce No access tocode
SVN Other Mercurial
0%
5%
10%
15%
20%
25%
30%
35%
40%
Most difficult part of API doc?
Understandcode
Get info fromengineers
Create non-refdocs
Understandaudience
Identifydependencies
0%
5%
10%
15%
20%
25%
30%
35%
40%
45%
50%
Percent
How did you learn what you needed to know?
0%5%
10%15%20%25%30%35%40%45%50%
Takeaways from survey
• Java, Eclipse, Git are popular
• Become familiar with getting info from both source code and developers
• Become a self-learner but also interact heavily with engineers
• REST APIs are by far most common
• Automating REST API doc isn’t all that common
Programmableweb.com: API Directory
12,000 + web APIs
What design trends or patterns do we see among popular API doc
sites?
Stripe API
Code responses next to doc.
https://stripe.com/docs/api
Single page scroll w/ TOC highlight
Third column to show responses or code samples.
http://crimson-cormorant.cloudvent.net/
Jekyll API doc theme from CloudCannon
Bootstrap scollspy demo
Yelp API
One seamless websitematching product
branding.
http://www.yelp.com/developers/documentation
Twilio API
One output, with nav tabs to show
different languages
http://www.twilio.com/docs/api/rest/conference
Twitter API
Interactive, real-time requests based on your
auth key
Dynamically inserted API keys
into code samples.
https://stripe.com/docs/api
Foursquare API
Often begin with Getting Started section,
providing a sample “Hello World” tutorial
https://developer.foursquare.com/start
Youtube API
Lots of code samples, usually with syntax
highlighting and surrounding commentary.
https://developers.google.com/youtube/v3/code_samples/apps-script
8 design trends with API doc
1. Third column to show responses & code2. Single page scroll with scrollspy TOC highlight
and floating sidebar3. Seamless website matching product branding4. Nav tabs to show different code samples5. Code syntax highlighting6. Hello World getting started section7. Interactive, personalized API explorer 8. Static site generators that process Markdown
syntax
Some non-trends
1. PDF output
2. Short pages
3. Multiple (highly duplicate) outputs of content for different audiences
4. DITA or XML authoring models
5. EPUB formats
6. Comments on pages
7. Wikis
8. Video tutorials
Slides + recording + code samples are freely downloadable
Tom Johnsonhttp://idratherbewriting.com@tomjohnson
Image credits
• slide 2: "API consumers want reliability, documentation and community." Programmableweb.com. http://bit.ly/progwebsurvey
• slide 3: “10 Reasons Developers Hate Your API” (and what to do about it). By John Musser. Slideshare. http://slidesha.re/1pnnDRf
• slide 4: Mars, once. By Kevin Dooley. http://bit.ly/ZFYI0T
• slide 15: Spinning gears. By Brent 2.0. Flickr. http://bit.ly/1DexWM0
• slide 21: Continental Drift. Wikipedia. http://en.wikipedia.org/wiki/Continental_drift
• slide 24: Programmableweb Research Center. http://www.programmableweb.com/api-research