STC Summit 2015: API Documentation, an Example-Based Approach

© 2015 - Lois Patterson
An example-based approach
(by Lois Patterson)
Creating Good API
Documentation

What we will discuss
• Why you want to document APIs
• What APIs are (especially REST APIs)
• How to document APIs, with a focus on
examples

Why API Documentation?
As an API documentation writer, you can:
• Wear many hats
• Demonstrate unique, sought-after skill sets
• Work with cutting-edge technology
• Work in a growing space, not a shrinking one

Why APIs Matter
• Explosive growth (maybe 200K in 2014?)
• Salesforce, eBay, PayPal, Facebook – Success
by API
• LEGO®-like approach to software
development
• We take interlocking apps for granted now

What is an API
• Application Programming Interface
• Snap a software widget into other software
“enablers of remix culture”
“a way for companies and developers to talk
to each other and build off of each other”
(The Atlantic)

What is an API
• Example: Many APIs together in one app

What is an API
• With an API, “their” software can use and
manipulate “your” software (the parts that
you want to make available)
• Revolutionary and simple
• Focus of this presentation is Internet-enabled
REST APIs

Not just skilled developers
You use APIs
Do you ever embed YouTube videos in your
blog?
<iframe width="560" height="315"
src="//www.youtube.com/embed/LJr6Fkn
ZhpM" frameborder="0"
allowfullscreen></iframe>
YouTube provides that code with Share.

YouTube Embed Code

API to embed video

(Flickr, user davenielsen)
“The cloud”? IoT? Think APIs.

API Mashups
• Mashup: Glue unrelated bits and pieces
together into a new program
• Google Maps API + a review API + developer
intelligence make a searchable app that tells
us cool restaurants open on Sunday
• Open data great for mashups
• Cloud, InternetOfThings, open data, big data,
social

Vast world of APIs
• ProgrammableWeb.com - tens of thousands
of APIs, mashups
• Public APIs for:
Maps
XBox Music Developer
Birdsongs
Facial recognition
Try a search yourself!
• Single application may use multiple APIs

APIs: User Analysis
• Typical API user: a software developer
• Mass-market API
Large user base
Less skilled users
• YouTube, Facebook, MailChimp
• Simpler APIs More users

Example: Multiple API Usage
Twitter API, AlchemyAPI, Python
language

Non-glamorous APIs too
• Device driver APIs
• Internal company APIs
• APIs available to select customers
• Programming language libraries
• Even more of these than public, obvious APIs

Why API docs matter
• Without documentation, an API is almost
completely inaccessible.
• For a determined hacker, perhaps possible.
• For typical user without docs, disaster.
• API docs make the API product possible,
much more so than for GUI software.
• Developers do RTFM (read the … manual) for
APIs.

Example: Stripe API Docs

Good APIs good API docs
• Wear our tech writer hats again
• Start with a good API to make good API docs
• Consistency
• Yes, just like other products

Basic techcomm principles
• We know how to get good docs
• Start with a good product
• Start with a good API to make good API docs
• Consistency
• Just like other products

REST APIs in a Nutshell
• Verbs (GET, POST, PUT, DELETE, and
sometimes PATCH)
• Nouns (Also called objects or resources)
• Apply verbs to nouns
• Client sends a request (verb + noun) to server
• Server responds to request (a response)

• Verbs + nouns
• Requests + responses
• (And authentication and headers and other
details)

• REST API – a simple and intuitive language
• Guess which company does this with its REST
API?
o Get a movie_ID
o Post (create) a person_ID
o Put (edit by replacing) a rating_ID
o Delete an entry_ID (from a queue)

Example: API Consistency and Use
Cases in Netflix
Endpoint for a movie title, by title ID:
http://api-public.netflix.com/catalog/titles/movies/title_id
Endpoint for a TV program, by program ID:
http://api-
public.netflix.com/catalog/titles/programs/program_id
Endpoint for a person, by person ID:
http://api-public.netflix.com/catalog/people/person_id

How about PayPal?

Some RESTful APIs with great docs
Netflix Twitter
Github Facebook
PayPal New York Times
Google Stripe
SoundCloud Amazon

Why are these good API docs?
• Netflix – Well-done API (although Netflix no
longer allows just anyone to use it)
• Soundcloud – Nicely designed, organized
information
• Twitter - Clear definitions of objects and
what you can do with them
• Github – Simple, easy, and everything is
there

Good API with good API docs
• Be involved in the beginning.
• Read design documents (they exist, right?)
• Or write the design document
• Write some sample documentation for this
fledgling API – doc first?
• Standard Agile--QA, Tech Pubs,
Development, Product Management work
together in the design phase

Important features of a good API
• Consistency
• Good error messages
• Clear naming conventions
• Just like for any other software product!

Can your API be as easy as
YouTube?
• Yes! For at least a few features.
• YouTube includes more complicated
features:
https://developers.google.com/youtube/
• A lot of work to get something that simple
• Typical Twitter program (Python) to get a
mass of tweets and save them to a file using
the RESTful API: about 35 lines

API success
• Want mass-market adoption?
• Think Simple.

What does an API look like?
• Not just code
• You can visualize APIs

API Demonstration and Testing
Tools
• Swagger (Django REST Swagger)
• Atlassian REST browser
• Google Advanced REST client
• cURL
Show AND Tell with these tools.
May need developer help—this is for
everyone’s benefit!

New York Times Example

Pet Store Swagger

What goes in the POST box?
JSON: Common format for defining objects and
responses in REST APIs.
{
"name":"Naive Cash Discounting USD",
"format":"f3ml",
"definition":
"<f><n>ExtendModelWithBootstrappedInterpolationCurve</n><a><n>AutoSort</n><v><r>
F</r></v>
<n>BaseModel</n><v><r><s>${-
1}</s></r></v><n>BootstrappingObjective</n><v><r><s>SingleCurrencyValue</s><
/r></v>
<n>CurveTag</n><v><r><s>USD</s><s>DiscountCurve</s></r></v><n>Inter
polationMethod</n><v><r><s>LogLinear</s></r></v>
<n>MarketDataTag</n><v><r><s>CashDeposit:USD</s><s>CashDepo</s></r></v><n>ModelName</n><v><r><s></s></r></v></a></f>"
}

Flickr App Garden
https://www.flickr.com/services/api/explore/?method=flickr.photos.search
A place where developers can showcase the applications they've
created and where you can find new ways to explore Flickr.

Your first application

PayPal test environment
PayPal
https://developer.paypal.com/docs/classic/lifecycle/ug_sandbox/

API docs should include …
• Description
• Tutorials
• Examples (Snippets, working apps)
• Sandbox test environment
• FAQs

Your API docs should have …
• Clear versioning. (And when coding, use
version number of the API.)
• Last-verified date, particularly for Web apps.
• Working code samples
• Suggestions for using API

Twitter helps the API user
Twitter site:
There are a few great ways to follow the changes we make to
the Twitter platform:
• Follow @twitterapi.
• Keep track of our Developer Blog and Discussions.
• See the recently updated documentation.
• Consult the Platform Calendar.

Twitter API doc page

How do I get code samples?
• Laziness and theft encouraged! (Not quite)
• Developers and Test engineers have created
samples for tests (or they should)
• Find and take these samples
• Agree on a standard style for docs
• Build more based on these samples

Do I need to code?
• Empathy with our users is a core requirement
for a tech writer
• Learn to read and edit code
• Increase your code-creation abilities
• Coursera, Udacity, Khan Academy, etc.
• Use support groups
• Code samples are the best-loved, but not the
only documentation

API Tutorial to try
Sarah Maddox, previously of Atlassian and now
of Google, wrote this tutorial:
http://bit.ly/1SmxwdY
(Or look it up at ffeathers.wordpress.com )
Learn about code, docs, API design in one go!

Resources (or the neverending
story)
• Impossible to keep up, but here’s a text file I
have on Google Drive (including links in this
presentation):
http://tinyurl.com/oqfm2mf

Enjoy documenting APIs!
• Lots of energy and opportunity in this field
• Always a chance to learn something new

L.Patterson@fincad.com
@LoisRP

STC Summit 2015: API Documentation, an Example-Based Approach

More Related Content

What's hot

Viewers also liked

Similar to STC Summit 2015: API Documentation, an Example-Based Approach

Recently uploaded

STC Summit 2015: API Documentation, an Example-Based Approach