1. API Documentation Workshop:
Introduction to APIs
By Tom Johnson
www.idratherbewriting.com
January 24, 2015

2. "Complete and accurate documentation" is most important factor in APIs, according to
a survey by @programmableweb. 250 respondents.
Important factors in API doc

3. Presentation by John Musser, founder of programmableweb.com,
which has directory of 12,000+ APIs

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

8. Slides + recording + code samples are
freely downloadable

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

10. Helpful to install for activities
• Eclipse for Java developers
• Chrome
• Chrome JSON Formatter extension
• Chrome Advanced REST client
• Sublime Text (Mac) or Notepad++ (Win)
• Git
No need to have prior knowledge of programming…

11. Download workshop files
1. Go to
https://github.com/tomjohnson1492/apiwor
kshop.
2. Click Download Zip. (Or bonus, clone the
repo.)
3. Unzip.

12. Tentative Outline
1. Introduction to API doc
2. Deep dive into REST API doc
3. Deep dive into code samples
3. Deep dive into Java and Javadoc

13. INTRODUCTION TO API DOC

14. Questions welcome at anytime
• What’s the biggest question you have about
API documentation?

15. Some basics about the API landscape
System B
System 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.

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

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

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

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

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

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

22. Pros/cons with Platform APIs
Pros
Performance: Performance is faster. (REST APIs struggle
with latency for web calls.)
Security: More secure.
Cons
Language 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.

23. API doc includes non-ref doc
Although reference doc tends to receive the
most attention, these docs are just one part of
API documentation. What technical writers
often work on is the implementation guide or
programmer’s guide on how to use the API. This
guide covers task-based information that shows
endpoints or classes used in particular
workflows and sequences to accomplish goals.

25. REST API basics
URLs requests return specific data HTTP Request
Response

26. Responses in JSON or XML
Configuration
parameters
ResponseinJSONformat

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
Knowing what parameters
you can include with an
endpoint is a huge part of the
REST API documentation.

28. cURL calls
HTTP requests are often demonstrated through
cURL calls, with different HTTP methods:
GET – retrieve
POST – edit
PUT – create
DELETE – 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.

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

30. Autodoc possibility: Swagger spec

31. RAML (REST API modeling language)

32. Swagger UI can parse the Swagger
syntax and render an output
Generates an endpoint
based on values you
enter

33. Mashery with Klout
Doc becomes
interactive
when you’re
signed in.
http://developer.klout.com/io-docs

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

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

36. Information survey on my blog
• 42 respondents working in API documentation
• Many people polled from API Documentation
group on Linkedin + blogosphere

37. Types of APIs that writers document
0%
10%
20%
30%
40%
50%
60%
70%
80%
90%

38. Are you automating REST API docs?
No Yes N/A
0%
10%
20%
30%
40%
50%
60%
70%
Percent

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

40. Authoring tools used by API doc
writers
0
10
20
30
40
50
60
70
80

41. Do you test out the API calls used in
your doc yourself?
Yes No Sometimes
0%
10%
20%
30%
40%
50%
60%

42. What IDE do you use?
Eclipse None Visual Studio IntelliJ IDEA Xcode Other
0%
5%
10%
15%
20%
25%
30%
35%
40%
45%
50%

43. Most common programming
languages tech writers know
0
5
10
15
20
25

44. Do developers write the initial API
documentation in the source code?
Yes No Sometimes
28%
29%
30%
31%
32%
33%
34%
35%
36%
37%

45. Do you write doc by looking in the
source code?
Yes No
0%
10%
20%
30%
40%
50%
60%
70%

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

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

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

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

50. Tom Johnson
http://idratherbewriting.com
@tomjohnson

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