api documentation -- presentation to east bay stc chapter
TRANSCRIPT
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
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
Some basics about the API landscape
System BSystem 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
DEEP DIVE INTO PLATFORM APIS
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
Doxygen
Good example of source-gen. doc
https://www.dropbox.com/developers/coreEach 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
DEEP DIVE INTO REST APIS
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
Documenting parameters is essential.
cURL calls
GET – retrieve
POST – edit
PUT – create
DELETE – remove
Use cURL to demo calls
REST API workflow
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
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
DELETEPUT
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 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://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.
Flickr Result
More details on the API callsGo here for details: http://bit.ly/restapiexamples
Recommended Resource
http://bit.ly/docrestapis
API DOCUMENTATION SURVEY
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%
PUBLISHING TRENDS WITH APIS
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
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/
QUESTIONS TO CONSIDER
Big questions to answer
Am I technical enough to excel in API documentation?
Big questions to answer
Is API documentation dry and boring?
Big questions to answer
How do I get into API documentation in the first place?
