Whether you are working with enterprise software, social networks, the Internet of Things, or various consumer-based applications, interoperability through easy-to-use APIs is crucial for product success.We will tour through some consumer product API documentation sets, like those of Twitter, Flickr, Facebook, and others, and see what works and what does not. We will look at how tools like Swagger are used to demonstrate and document APIs. Learn how to advocate for a usable API design and to develop good API documentation from the beginning.

1. © 2014 - Proprietary and Confidential Information of FINCAD
An example-based approach
(by Lois Patterson)
Creating Good API
Documentation

2. © 2014 - Proprietary and Confidential Information of FINCAD
Why APIs and API Documentation
Matters
● Explosive growth in APIs: everyone wants
them (maybe 200K in 2014?)
● Amazon’s success linked to API-based
approach
● Lego-based approach to software
development--natural evolution of object-
orientation

3. © 2014 - Proprietary and Confidential Information of FINCAD
Vast world of APIs
• ProgrammableWeb.com - tens of thousands
of APIs, mashups
• APIs for:
• Burning Man
• Birdsongs
• Facial recognition
• ?

4. © 2014 - Proprietary and Confidential Information of FINCAD
Not just developers
You know how to 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.

5. © 2014 - Proprietary and Confidential Information of FINCAD
YouTube Embed Code

6. © 2014 - Proprietary and Confidential Information of FINCAD
API to embed video (2)

7. © 2014 - Proprietary and Confidential Information of FINCAD
Why API docs matter
• Without documentation, an API is almost
completely inaccessible.
• For a determined hacker, perhaps possible.
• For the regular 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.

8. © 2014 - Proprietary and Confidential Information of FINCAD
Good APIs good API docs
• Start with a good API to make good API docs
• Consistency!

9. © 2014 - Proprietary and Confidential Information of FINCAD
REST APIs in a Nutshell
• Verbs (GET, POST, PUT, DELETE -- maybe PATCH, but it is
controversial)
• Nouns (Also called objects or resources)
• Apply verbs to nouns
• Simple and intuitive? For example:
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)

10. © 2014 - Proprietary and Confidential Information of FINCAD
CRUD principle
• CRUD (Create/Read/Update/Delete)
• But what you create, what you select to
read or update or delete, is not
necessarily simple

11. © 2014 - Proprietary and Confidential Information of FINCAD
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

12. © 2014 - Proprietary and Confidential Information of FINCAD
How about PayPal?

13. © 2014 - Proprietary and Confidential Information of FINCAD
Some RESTful APIs with great docs
● Netflix
● Twitter
● Github
● Facebook
● PayPal
● Flickr
● Google

14. © 2014 - Proprietary and Confidential Information of FINCAD
Why are these good APIs?
Netflix - Just a well-done API (sadly, it has not
been updated and no publicly available keys
anymore)
Twitter - Really clear definition of objects and
what you can do with them
Github - Simple and everything is there

15. © 2014 - Proprietary and Confidential Information of FINCAD
How do I help make a good API?
● Be involved in the beginning.
● Read design documents (they exist, right?)
● If no design document, can you write it?
● Try writing some sample documentation for
this fledgling API – doc first?
● Best is if QA, Documentation, Development
(not to mention Product Management) are
together in the design phase

16. © 2014 - Proprietary and Confidential Information of FINCAD
Important features of a good API
● Consistency
● Good error messages
● Clear naming conventions
● Just like for any other software product!

17. © 2014 - Proprietary and Confidential Information of FINCAD
API standards?
● Very popular APIs tend to become de facto
standards
● Standards include: REST, RPC, etc.
● REST is probably winning the day

18. © 2014 - Proprietary and Confidential Information of FINCAD
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
If you want mass-market adoption, simplicity is
paramount.

19. © 2014 - Proprietary and Confidential Information of FINCAD
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!

20. © 2014 - Proprietary and Confidential Information of FINCAD
Pet Store Swagger

21. © 2014 - Proprietary and Confidential Information of FINCAD
Pet Store Swagger

22. © 2014 - Proprietary and Confidential Information of FINCAD
Model in Swagger

23. © 2014 - Proprietary and Confidential Information of FINCAD
Model

24. © 2014 - Proprietary and Confidential Information of FINCAD
What goes in the POST box?
{
"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>"
}

25. © 2014 - Proprietary and Confidential Information of FINCAD
Model by slug

26. © 2014 - Proprietary and Confidential Information of FINCAD
Flickr API Garden
Look what you can do:
https://www.flickr.com/services/api/explore/?method=flickr.photos.search

27. © 2014 - Proprietary and Confidential Information of FINCAD
PayPal test environment
PayPal
https://developer.paypal.com/docs/classic/lifecycle/ug_sandbox/

28. © 2014 - Proprietary and Confidential Information of FINCAD
API docs should include …
• Description
• Tutorials
• Examples (Snippets, working apps)
• Sandbox test environment
• FAQs

29. © 2014 - Proprietary and Confidential Information of FINCAD
Your API docs should have …
● Clear versioning. (And when coding, use
version number of the API.)
● Last-verified date, particularly for Web apps.
● FAQ
● Working code samples
● Suggestions for using API

30. © 2014 - Proprietary and Confidential Information of FINCAD
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.

31. © 2014 - Proprietary and Confidential Information of FINCAD
Backlinks
Twitter

32. © 2014 - Proprietary and Confidential Information of FINCAD
Twitter API doc page

33. © 2014 - Proprietary and Confidential Information of FINCAD
How do I get code samples?
• Laziness! I encourage it!
• Developers have created samples for tests (or
they should!)
• Quality Assurance has created samples for
tests
• Take these samples
• Agree on a standard style
• Build more based on these samples

34. © 2014 - Proprietary and Confidential Information of FINCAD
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
• All code samples are documentation; not all
documentation is code.

35. © 2014 - Proprietary and Confidential Information of FINCAD
API Tutorial to try
Sarah Maddox, previously of Atlassian and now
of Google, wrote this tutorial:
http://ffeathers.wordpress.com/2014/09/28/wa
nt-a-rest-api-to-play-with/
Learn about code, docs, API design in one go!

36. © 2014 - Proprietary and Confidential Information of FINCAD
Resources
http://jacobian.org/writing/what-to-write/
http://www.theparticlelab.com/good-api-documentation/
http://ffeathers.wordpress.com/
http://www.idratherbewriting.com/
http://www.programmableweb.com/
https://helloreverb.com/developers/swagger
http://stackoverflow.com/questions/2001899/creating-great-api-documentation-tools-and-techniques
http://stackoverflow.com/questions/1515326/what-do-you-consider-good-api-documentation
https://www.youtube.com/watch?v=C5ws9ZNUfxc
http://www.apiacademy.co
http://apievangelist.com/2014/09/20/my-api-101-workshop-at-apistrat-in-chicago-next-week
and more!

37. © 2014 - Proprietary and Confidential Information of FINCAD

38. © 2014 - Proprietary and Confidential Information of FINCAD
L.Patterson@fincad.com
@LoisRP