API Documentation -- Presentation to East Bay STC Chapter

Survival Strategies for
API Documentation
By Tom Johnson
www.idratherbewriting.com
May 7, 2015
East Bay STC

"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

Presentation by John Musser, founder of programmableweb.com,
which has directory of 12,000+ APIs. http://bit.ly/jmusserslideshare

Flickr http://bit.ly/ZFYI0T

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
Download for free at
http://bit.ly/stcintercoma
piissue

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

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

SDK versus API
• API (application programming interface):
Endpoints, classes, or other functions.
• SDK (software development kit):
Implementation tooling to support the API.

At least two deliverables
API Reference User Guides

Outline
1. Platform APIs
2. REST APIs
3. API documentation survey
4. API doc publishing trends
5. Questions to consider

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.

Comments get rendered into Javadoc

Good example of source-gen. doc
https://www.dropbox.com/developers/core
Each language
uses a different
doc generator.
https://www.dropbox.com/developers/core

Who writes the Javadoc?
• Usually engineers write initial draft.
• Tech writers edit.
• Tech writers might work in a doc branch.
Doc
branch
Main
branch
mergeCode
repo

Pros of in-source documentation
- Avoids doc drift
- Allows engineers to
document
- Includes tooltips in
IDE
Doc
SrcDoc Src
Continental drift
Wikipedia: http://bit.ly/contdriftwiki

Problem: Gives illusion of real doc
“… auto-generated
documentation is worse than
useless: it lets maintainers fool
themselves into thinking they
have documentation, thus
putting off actually writing good
reference by hand. If you don’t
have documentation just admit
to it. Maybe a volunteer will
offer to write some! But don’t
lie and give me that auto-
documentation crap”. – Jacob
Kaplan Moss
Looks real but
isn’t.
Flickr. http://bit.ly/1F1et36.

Problem: Doesn’t integrate
Like a HAT-produced
webhelp file, the
auto-doc is its own
website.

A developer who
creates the API
may assume too
much of the
audiences’
technical ability.
Problem: Curse of Knowledge
http://bit.ly/wsjpinker

Pros/cons with Platform APIs
Pros
- Performance
- Security
Cons
- Language coverage
- Upgrades
Flickr: http://bit.ly/serverroomflickr

http://www.programmableweb.com/api-research

REST API basics
URLs requests return specific data HTTP Request
Response
Flickr.galleries.getPhotos
endpoint

Add parameters to endpoints
https://api.flickr.com/services/rest/?method=flic
kr.activity.userPhotos&api_key=1712c56e30dbad
5ef736245cda0d1cb9&per_page=10&format=js
on&nojsoncallback=1
Documenting parameters is
essential.

cURL calls
GET – retrieve
POST – edit
PUT – create
DELETE – remove
Use cURL to demo calls

Sample endpoints
api_site.com/{apikey}/users
// gets all users
api_site.com/{apikey}/users/{userId}
// gets a specific user
api_site.com/{apikey}/rewards
// gets all rewards
api_site.com/{apikey}/rewards/{rewardId}
// gets a specific reward
api_site.com/{apikey}/users/{userId}/rewards
// gets all rewards for a specific user
api_site.com/{apikey}/users/{userId}/rewards/{rewardId}
// gets a specific reward for a specific user
A “RESTful web service”
has “endpoints” that
return “resources.”

Responses (JSON or XML)
{
"user”:"1234",
"userName":"Tom",
"userCreatedDate":"09021975",
”userStatus: "active"
}
A JSON object consists
of key: value pairs.

Some responses contain
arrays.

Get familiar with Developer Console

HTTP requests have methods
GET
POST
DELETE
PUT
Usually only submitted
using cURL.

Viewing methods for resources
Look on the Network
tab of your console.

EventBrite API example
Let’s get some event
details using the events
endpoint from the
EventBrite API.
https://developer.eventbrite.com/docs/event-details/

Get eventbrite event details
Endpoint:
eventbrite.api.com/v3/events/{event_id}
Endpoint with values:
https://www.eventbriteapi.com/v3/events/14635401881/
?token=C4QTJZP64YS5ITN4JSPM
Response:
{
"resource_uri":
"https://www.eventbriteapi.com/v3/events/14635401881/",
"name": {
"text": "API Workshop with Sarah Maddox",
},
"description": {
"text": "This is a practical course on API technical writing, consisting of…

Open your console and
inspect the payload

Accessing JSON using dot notation
To get the values from
the JSON, use dot
notation. If our object is
named data, then
data.name.text gets
that value.

 Activity: View payload values
1. In Chrome, open the JavaScript Console by
going to View > 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.

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.

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
81785c09989ba8032e&gallery_id=66911286-
72157647277042064&format=json&nojsoncallback=1
Response:
{
"score": 92.2655186160279,
"scoreDelta": {
"dayChange": 0.00044535591406713593,
… }

 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.

$("#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.

More details on the API calls
Go here for details:
http://bit.ly/restapiexamples

Recommended Resource
http://bit.ly/docrestapis

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

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 to
code
SVN Other Mercurial
0%
5%
10%
15%
20%
25%
30%
35%
40%

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

How did you learn what you needed to
know?
0%
5%
10%
15%
20%
25%
30%
35%
40%
45%
50%

Programmableweb.com: API Directory
12,000 + web APIs

What design
trends or patterns
do we see among
popular API doc
sites?
Flickr: http://bit.ly/1sWdnln

Yelp API
One seamless website
matching product
branding.
http://www.yelp.com/developers/documentation

Twilio API
One output, with
nav tabs to show
different
languages

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
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

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

Automating API docs
• Swagger: 600+ repos
• RAML: 180+ repos
• API Blueprint: 120+ repos
– slide notes from Jennifer Rondeau presentation on
REST API Doc

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.

Swagger UI’s output
http://petstore.swagger.wordnik.com/

Big questions to answer
Am I technical enough to
excel in API documentation?

Is API documentation dry
and boring?

How do I get into API
documentation in the first
place?

Tom Johnson
http://idratherbewriting.com
@tomjohnson

API Documentation -- Presentation to East Bay STC Chapter

More Related Content

What's hot (18)

Viewers also liked (9)

Similar to API Documentation -- Presentation to East Bay STC Chapter (20)

Recently uploaded (20)

API Documentation -- Presentation to East Bay STC Chapter

Editor's Notes