Post on 16-Jul-2015
transcript
API Documentation Workshop: Introduction to APIs
By Tom Johnson
www.idratherbewriting.com
January 24, 2015
"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
Slides + recording + code samples are freely downloadable
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.
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…
Download workshop files
1. Go to https://github.com/tomjohnson1492/apiworkshop.
2. Click Download Zip. (Or bonus, clone the repo.)
3. Unzip.
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
INTRODUCTION TO API DOC
Questions welcome at anytime
• What’s the biggest question you have about API documentation?
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.
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.
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.
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.
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
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