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