api documentation workshop tcworld india 2015
TRANSCRIPT
API Documentation Workshop
By Tom Johnson
www.idratherbewriting.com
March 13, 2015
tcworld India 2015
"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
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/stcintercomapiissue
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
Outline
1. Overview of API doc
2. REST Deep Dive
3. JavadocDeep Dive
OVERVIEW OF 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.
Flickr: http://bit.ly/1DexWM0
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.
API Reference Programmer Guides
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
Wikipedia: http://bit.ly/contdriftwiki
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
Re
spo
nse
Flickr.galleries.getPhotosendpoint
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
GET – retrieve
POST – edit
PUT – create
DELETE – remove
Many sample REST calls are demonstrated in cURL.
Information survey on my blog
- 42 respondents
- 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
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
DEEP DIVE INTO REST APIS
REST
• Client-server architecture: You send a request and get a response back. REST is the model of the web. REST APIs also called “web APIs.”
• REST = “representational state transfer” – data transfer modeled after the web.
• Protocol transfer is HTTP. Requests are made through URLs.
• Can see the response in the browser.
• Responses are stateless -- not remembered.
Sample endpointsapi_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
In a well-designed API, you can predict the
logic of the requests.
A “RESTful web service” has “endpoints” that return “resources.”
Responses (usually JSON)
{"user”:"1234","userName":"Tom","userCreatedDate":"09021975",”userStatus: "active"
}
A JSON object consists of key: value pairs.
Some objects contain lists of items in brackets [ ]. Here the photo object
contains an “array.”
Get familiar with Developer Console
Console.log
In code samples, you can use console.log(data)
to log an object called “data” to the console. Then
“inspect the payload.”
HTTP requests have methods
GET
POST
DELETEPUT
The methods available for each resource differ. DELETE methods aren’t
usually passed in regular web page code for
security reasons. Usually only submitted using
cURL.
Look on the Network tab of your console
when you make a web request, and you can see the method for
each request.
Activity: Download workshop files
1. Go to the API workshop Github repo: https://github.com/tomjohnson1492/apiworkshop
2. If you have git installed, download the files by opening Terminal and typing git clone https://github.com/tomjohnson1492/apiworkshop.git.
3. If you don’t have git, just click Download ZIP.
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…
BTW, the API key values on my slides are
fake (but not in the workshop
files).
<script>
var url =
"https://www.eventbriteapi.com/v3/events/14635401881
/?token=C4QTGZP64YS5ITN4JSPM";
$.getJSON( url, function( data ) {
console.log(data);
var content = "<h2>" + data.name.text + "</h2>"
+ data.description.html;
$("#eventbrite").append(content);
});
</script>
<div id="eventbrite"></div>This is a simple way to
display JSON content on a web page.
Open your console and inspect the payload that is logged to the console
via console.log in the code.
Accessing JSON using dot notationTo 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://tomjohnson1492.github.io/apiworkshop/eventbrite.html. (Or open eventbrite.htmlfrom the workshop files.)
3. Expand the description and name sections in the payload logged to the console.
Code samples should be simple
- Focus on call and response (input/output).
- Use minimal styling to avoid distraction.
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.
Example: Get Klout Score
Klout has an interactive console.
http://developer.klout.com/io-docs
Get Klout score
Endpoint:
user.json/{kloutid}/score
Endpoint with values:
http://api.klout.com/v2/user.json/1134760/score
?key=urgey4a79njk6df6xx4p64dr
Response:
{
"score": 92.2655186160279,
"scoreDelta": {
"dayChange": 0.00044535591406713593,
...
}
We have to call another resource first
to get the Klout ID.
Get Klout ID from Twitter handle
Endpoint:
identity.json/twitter?screenName={username}
Endpoint with values:
http://api.klout.com/v2/identity.json/twitter?screenName=tomjohnson&key=urgeykj79n5x6df6xx4p64dr
Response:
{
"id": "1134760",
"network": "ks"
}
<script>
var url =
"http://api.klout.com/v2/user.json/1134760/score?
key=urgey4a79n5x6df6xx4p64dr&callback=?";
$.getJSON( url, function( data ) {
console.log(data.score);
$("#kloutScore").append(data.score);
});
</script>
<h2>My Klout Score</h2>
<div id="kloutScore"/> Tip: jQuery makes life a lot simpler.
Here’s the result:
Get Klout Score using PHP
http://bradsknutson.com/blog/display-klout-score-with-klout-api/
Use whatever language you want to implement
the web API calls.
Get Klout Score using Python
https://klout.readthedocs.org/en/latest/#quickstart
This is why providing code samples can be
problematic. Where do you stop? Ruby, Java,
Node, Python, JavaScript?
Example: Get influencees
Reference docs don’t tell you all you need to know.
For example, what are influencers and influencees?
Get klout influencees
Endpoint: user.json/{kloutid}/influence
Endpoint with values:
http://api.klout.com/v2/user.json/1134760/influ
ence?key=urgerjy4a79n5x6df6xx4p64dr
Response:
{
"score": 92.2655186160279,
"scoreDelta": {
"dayChange": 0.00044535591406713593,
...
}
API keys regulate usage and prevent
servers from abuse by too many calls.
<script>
var url =
"http://api.klout.com/v2/user.json/1134760/influence?ke
y=u4r7nd397bj9ksxfx3cuy6hw&callback=?";
$.getJSON( url, function( data ) {
console.log(data);
$.each( data.myInfluencees, function( i, inf ) {
$("#kloutInf").append('<li><a
href="http://twitter.com/'+inf.entity.payload.nick +
'">' + inf.entity.payload.nick + '</a></li>');
});
});
</script>
<h2>My influencees</h2>
<ul id="kloutInf"></ul>
</body></html>
jQuery’s eachmethod can iterate through items in an
array.
The result
Activity: Change endpoint parameters
1. Open klout_influence.html in workshop files, or grab source from http://tomjohnson1492.github.io/apiworkshop/klout_influence.html.
2. Change the Klout ID to something else such as 876597 (@whitehouse).
3. View the file in the browser to see the influencees.
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://tomjohnson1492.github.io/apiworkshop/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.
Flickr Result
More details on the API callsGo here for details: http://bit.ly/restapiexamples
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 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
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
Auto-generated reference doc solutions
• Swagger
• RAML
• Enunciate
• API Blueprint
• Mashery I/O
• Miredot (Java only)
• APIdocjs.com
Most common automated options
“Github stats (with caveat: these are repos, do not necessarily all represent implementations):
Swagger: 600+ repos (270+ JS, 80+ Java, 31 Python)RAML: 180+ repos (54 JS, 21 Java, nothing listed for Python)I/O Docs: 30-40 repos (mostly JS, some Java)API Blueprint: 120+ repos (again, mostly JS, some Java, some Python)”
– 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/
Swagger basics
• Swagger is a spec, a schema for describing your API in a standard way that tools can process. (Kind of like DITA.)
• “Swagger UI” is one tool that parses the Swagger spec from a JSON file. With this approach, the JSON file is separate from the source.
• There are also many Swagger libraries that integrate directly into API source code.
Activity: Check out Swagger
1. Go to http://petstore.swagger.wordnik.com/
2. Expand some of the sections.
3. Click Try it out in one of the sections.
Recommended Resource
http://bit.ly/docrestapis
JAVADOC DEEP DIVE
Sample Javadoc comment
Browse a full example from
Oracle. See the “Examples of Doc
Comments” section.
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#examples
Full Javadoc example
Java documentation itself is created with Javadoc (obviously).
http://docs.oracle.com/javase/7/docs/api/
Who uses Java + Javadoc
• Used by Java developers.• The most common document generator for Java
APIs.• Supported by Oracle.• Integrates directly into IDE that developers use.• Format is familiar to Java developers.• Output is skinnable but you can’t add non-ref
files to it.• Comment style is highly similar to most other
document generators.
Workshop sample code
In workshop files, go to sample_java_project
Workshop sample Javadoc
Default output from the standard Java doclet that parses
Javadoc tags.
Javadoc overview
There’s no search, but there is an index. Browse classes from
left pane or browse by packag.
Packages are folders for classes
This javadoc_tags package has two classes, summarized here.
Each class has 3 main sections
Each class in the Javadoc has 3 main
sections: Fields, Constructors, and
Methods. They have a summary first and then link to detailed sections
for each below.
Activity: Get familiar with Javadoc
1. In workshop files, open sample_java_doc / doc / index.html or go to http://tomjohnson1492.github.io/apiworkshop/sample_java_project/doc.
2. Browse both of the classes.
3. Click the links in the summary sections to jump to more detail.
Do developers write the initial API documentation in the source code?
Yes No Sometimes
28%
29%
30%
31%
32%
33%
34%
35%
36%
37%
Who writes the Javadoc?
• Engineers usually write it [poorly].
• Tech writers edit, fill in missing doc, clarify.
• Tech writers work in a doc branch.
Doc branch
Main branch
mergeCode repo
Can tech writers contribute to Java reference doc?
• Java libraries are highly technical. You must understand Java to contribute substantially.
• One of the things tech writers can contribute is style, says Joe Malin.
• Javadoc style is highly structured. You’re not just editing grammar.
Install Eclipse IDE for Java developers
You need an IDE to work with Java source files. Eclipse contains the JDK. Eclipse is the
most common.
Install the Java Development Kit (JDK)
The JDK is included in Eclipse, but the JDK includes the JRE,
which you may or may not have. Type java -version
to check.
Developers get files through source control software
Copy the clone URL and enter git clone
{url} in a Terminal prompt, replacing
{url} with the actual URL. https://github.com/tomjohnson1492/apiworks
hop
Install Git
You get source files using source control
such as Git, Mercurial, Perforce, etc. (Type
which git to see if you already have it.)
Activity: Import into Eclipse
1. In Eclipse, go to File > Import.
2. Expand General, select Existing Projects into Workspace. Then click Next.
3. In “Select Root Directory,” select the sample_java_project folder in the workshop files.
4. Click Finish.
5. In the project, expand the javadoc_tagspackage and click the .java files to view them.
Easy way to preview Javadoc
• Look in Javadoc pane at bottom of screen while using Eclipse.
The Javadoc tab lets you preview what the Javadocoutput will look like.
Java classes
• Classes are templates from which objects are constructed.
• Analogy: You download a resume template in Word, and then use it to create your own resume.
Class
Object 1 Object 2 Object 3
Another Example: From a general Bicycle blueprint, you make 3 three bicycle objects: Trek, Raleigh, and Giant.
Bicycle
- size
- roll()
Trek
- size
- roll()
Raleigh
- size
- roll()
Giant
- size
- roll()
“instantiate”
• “Instantiation” is the process of creating an object (an “instance”) from a class.
What a class looks like
public class ACMESmartphone {
// fields
// methods
}
Classes always say “class.” They have the same name as the file, and start with a capital letter. They don’t take
arguments, so no parentheses () appear after the class name.
“Public” is an access modifier that defines who can access this
class. Only public classes are included in Javadoc.
Javadoc tags versus comments
/**
*
*
*
*/
/*
*
*/
//
A slash followed by two asterisks indicates Javadoc content.
Just one asterisk is a regular comment. Same
with two slashes.
Activity: Understand Doc Block Tags
1. Open Eclipse.
2. Browse to javadoc_tags/ACMESmartphone.java.
3. Above the existing doc block, type /** and press return.
4. Go to a new line. Now type /* and press return.
5. Notice the difference?
Class descriptions/**
* Works like a regular smartphone but also tracks roadrunners.
* <p>
* The ACME Smartphone can perform similar functions as other smartphones, such
* as making phone calls, sending text messages, and browsing the web. However,
* <p>
* Note that the RoadRunner Tracker app requires you to be connected to wifi. It
* will not work on cellular data.
*
* @author Tom Johnson
* @version 2.0
* @since 1.3
*/
public class ACMESmartphone {
// content for class …
}
• Javadoc content appears before the class.
• Short description ends with first period. Long description then begins.
• Use <p> for paragraph breaks.
• Tags come at end.• HTML tags allowed
(e.g., <code>, <ul>)
Short description
Short description of the class appears on Class
Summary section of the package overview.
Short + long description
Both short and long descriptions appear on the
class page.
Available tags for the description
/** @author Joe Developer* @version 2.0* @see Dynamite* @since 1.3* @deprecated Use the {@link Dynamite class instead}*/
@param and @throws are used in methods rather than
classes.
See = “See also”Since = when the class was first included
Java methods
• Methods are subprograms that a class can do.
• Methods take arguments.• Methods often return values to
their caller.
Example: A calculator class might have the methods add, subtract, divide, multiple.
add(a, b) {
sum = a + b;
}
Methods for Calculator class
Add
subtract
Multiply
divide
Sample method
public class ACMESmartphone {
public String findRoadRunner(String city, String state) {
System.out.println("location: " + city + ", " + state);
// more logic…
}
} Methods appear inside of classes. They begin with lowercase and follow camelcase style.
Methods accept arguments. The arguments get passed into the logic of the method’s program.
/*** Gets the geocoordinates of roadrunners based on your city and
state.* * @param city the city you want to browse for roadrunners* @param state the state you want to browse for roadrunners* @return the coordinates of the roadrunner in your area* @throws IOException if you put integers instead of strings*/
public String findRoadRunner(String city, String state) {
System.out.println("location: " + city + ", " + state);System.out.println("getting geocoordinates of roadrunner.... ");System.out.println("roadrunner located at " + LongLat);return LongLat;
}
Documented method
Descriptions for methods are similar to classes. But @ tags include param, return, throws. The method’s code must match the tags or you get warnings in Javadoc.
@param tag guidelines
@param fuseLength the length of the fuse on the stick of dynamite
• @param is followed by parameter name
• Don’t specify data type since it’s shown in the method’s arguments
• Written as a lowercase phrase, without a period
• If multiple parameters, arrange by order or arguments in the method
• Required even if no descriptions are present
Generating Javadoc
1. Go to File > Export.2. Expand Java and select
Javadoc. Click Next.3. In left pane, select the
project & package you want.
4. In the right, select the check boxes next to the classes you want.
5. Click Finish.
Activity: Generate a Javadoc
1. In Eclipse, go to File > Export.
2. Select Java > Javadoc, and click Next.
3. Select javadoc_tags and expand it.
4. Select Dynamite and ACMESmartphone class check boxes.
5. Click Finish.
6. Compare how the classes and tags listed in the source end up in the Javadoc.
Doxygen
- Commonly used for C++.- 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.- Can skin.
Doxygen has GUI front-end
Specify the source directory of your files.
Sample: http://tomjohnson1492.github.io/apiworkshop/doxygenoutput/html/
Pitfalls of in-source documentation
1. Subject to Curse of Knowledge
2. Not task-focused
3. Suffers from lack of ownership
4. Doesn’t integrate with other content
5. Gives illusion of having real doc
Flickr. http://bit.ly/1CodnKM
A developer who creates the API may assume too much of the audiences’ technical ability.
Problem 1: Curse of Knowledge
http://bit.ly/wsjpinker
Auto-doc is feature-based doc approach. Task-based doc includes multiple calls and workflows in support of goals. It might make use of several different objects and methods across the reference doc.
Problem 2: Not task-focused
Problem 3: Lack of ownership
Auto-doc is a stray dog.
Auto-doc is owned like a stray dog or wiki is owned. Someone may contribute some food or a page without care for the whole. Tech writers feel less responsible when auto-doc is a separate from their output.
Flickr. http://bit.ly/1wau5NK
Problem 4: Doesn’t integrate
Auto-doc doesn’t integrate directly into a website except as a link from your other web pages. Like a HAT-produced webhelp file, the auto-doc is its own website.
Problem 5: 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.
Still, auto-doc is the way to go
1. Creates predictable layout.2. Integrates with IDE.3. Reduces documentation drift.4. At least engineers write something…
