More Related Content
Similar to STC Summit 2015: API Documentation, an Example-Based Approach
Similar to STC Summit 2015: API Documentation, an Example-Based Approach (20)
STC Summit 2015: API Documentation, an Example-Based Approach
- 1. © 2015 - Lois Patterson
An example-based approach
(by Lois Patterson)
Creating Good API
Documentation
- 2. © 2015 - Lois Patterson
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
- 3. © 2015 - Lois Patterson
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
- 4. © 2015 - Lois Patterson
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
- 5. © 2015 - Lois Patterson
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)
- 6. © 2015 - Lois Patterson
What is an API
• Example: Many APIs together in one app
- 7. © 2015 - Lois Patterson
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
- 8. © 2015 - Lois Patterson
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.
- 9. © 2015 - Lois Patterson
YouTube Embed Code
- 10. © 2015 - Lois Patterson
API to embed video
- 11. © 2015 - Lois Patterson
(Flickr, user davenielsen)
“The cloud”? IoT? Think APIs.
- 12. © 2015 - Lois Patterson
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
- 13. © 2015 - Lois Patterson
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
- 14. © 2015 - Lois Patterson
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
- 15. © 2015 - Lois Patterson
Example: Multiple API Usage
Twitter API, AlchemyAPI, Python
language
- 16. © 2015 - Lois Patterson
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
- 17. © 2015 - Lois Patterson
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.
- 18. © 2015 - Lois Patterson
Example: Stripe API Docs
- 19. © 2015 - Lois Patterson
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
- 20. © 2015 - Lois Patterson
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
- 21. © 2015 - Lois Patterson
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)
- 22. © 2015 - Lois Patterson
REST APIs in a Nutshell
• Verbs + nouns
• Requests + responses
• (And authentication and headers and other
details)
- 23. © 2015 - Lois Patterson
REST APIs in a Nutshell
• 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)
- 24. © 2015 - Lois Patterson
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
- 25. © 2015 - Lois Patterson
How about PayPal?
- 26. © 2015 - Lois Patterson
Some RESTful APIs with great docs
Netflix Twitter
Github Facebook
PayPal New York Times
Google Stripe
SoundCloud Amazon
- 27. © 2015 - Lois Patterson
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
- 28. © 2015 - Lois Patterson
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
- 29. © 2015 - Lois Patterson
Important features of a good API
• Consistency
• Good error messages
• Clear naming conventions
• Just like for any other software product!
- 30. © 2015 - Lois Patterson
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
- 31. © 2015 - Lois Patterson
API success
• Want mass-market adoption?
• Think Simple.
- 32. © 2015 - Lois Patterson
What does an API look like?
• Not just code
• You can visualize APIs
- 33. © 2015 - Lois Patterson
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!
- 34. © 2015 - Lois Patterson
New York Times Example
- 35. © 2015 - Lois Patterson
New York Times Example
- 36. © 2015 - Lois Patterson
Pet Store Swagger
- 37. © 2015 - Lois Patterson
Pet Store Swagger
- 38. © 2015 - Lois Patterson
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><p><n>AutoSort</n><v><r>
<b>F</b></r></v></p>
<p><n>BaseModel</n><v><r><s>${-
1}</s></r></v></p><p><n>BootstrappingObjective</n><v><r><s>SingleCurrencyValue</s><
/r></v></p>
<p><n>CurveTag</n><v><r><s>USD</s><s>DiscountCurve</s></r></v></p><p><n>Inter
polationMethod</n><v><r><s>LogLinear</s></r></v></p>
<p><n>MarketDataTag</n><v><r><s>CashDeposit:USD</s><s>CashDepo</s></r></v></p
><p><n>ModelName</n><v><r><s></s></r></v></p></a></f>"
}
- 39. © 2015 - Lois Patterson
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.
- 40. © 2015 - Lois Patterson
Your first application
- 41. © 2015 - Lois Patterson
PayPal test environment
PayPal
https://developer.paypal.com/docs/classic/lifecycle/ug_sandbox/
- 42. © 2015 - Lois Patterson
API docs should include …
• Description
• Tutorials
• Examples (Snippets, working apps)
• Sandbox test environment
• FAQs
- 43. © 2015 - Lois Patterson
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
- 44. © 2015 - Lois Patterson
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.
- 45. © 2015 - Lois Patterson
Twitter API doc page
- 46. © 2015 - Lois Patterson
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
- 47. © 2015 - Lois Patterson
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
- 48. © 2015 - Lois Patterson
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!
- 49. © 2015 - Lois Patterson
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
- 50. © 2015 - Lois Patterson
Enjoy documenting APIs!
• Lots of energy and opportunity in this field
• Always a chance to learn something new
- 52. © 2015 - Lois Patterson
L.Patterson@fincad.com
@LoisRP