These are slides from a presentation I gave to the East Bay STC chapter.

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

15. Comments get rendered into Javadoc

16. Doxygen

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

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

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

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

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

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

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

24. DEEP DIVE INTO REST APIS

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

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

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

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

29. REST API workflow

30. 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.”

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

32. Some responses contain
arrays.

33. Get familiar with Developer Console

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

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

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

37. 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…

38. Open your console and
inspect the payload

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

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

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('<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.

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 UI’s 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