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 developersYou use APIs

Do you ever embed YouTube videos in your blog?<iframe width="560" height="315" src="//www.youtube.com/embed/LJr6FknZhpM" 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: MapsXBox Music DeveloperBirdsongs Facial recognitionTry 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_IDo Post (create) a person_IDo Put (edit by replacing) a rating_IDo 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

http://developer.netflix.com/docs/REST_API_Reference

http://api-public.netflix.com/catalog/titles/movies/title_id

http://api-public.netflix.com/catalog/titles/movies/title_id

http://api-public.netflix.com/catalog/titles/programs/program_id



http://api-public.netflix.com/catalog/people/person_id

http://api-public.netflix.com/catalog/people/person_id


How about PayPal?


Some RESTful APIs with great docs

Netflix TwitterGithub FacebookPayPal 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>InterpolationMethod</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/

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

http://twitter.com/intent/user?screen_name=twitterapi

https://dev.twitter.com/blog

https://dev.twitter.com/discussions

https://dev.twitter.com/docs/recent

https://dev.twitter.com/calendar


Twitter API doc page

https://dev.twitter.com/rest/reference/get/friendships/show


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!

http://bit.ly/1SmxwdY

http://bit.ly/1SmxwdY


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


[email protected]@LoisRP

mailto:[email protected]

stc summit 2015: api documentation, an example-based approach

Software