Lois Patterson - Learning how to document APIs by example; soapconf 2014

© 2014 - Proprietary and Confidential Information of FINCAD

An example-based approach (by Lois Patterson)

Creating Good API Documentation


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


Vast world of APIs

• ProgrammableWeb.com - tens of thousands of APIs, mashups

• APIs for: • Burning Man • Birdsongs • Facial recognition • ?

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.


YouTube Embed Code


API to embed video (2)


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.


Good APIs good API docs

• Start with a good API to make good API docs • Consistency!


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)


CRUD principle

• CRUD (Create/Read/Update/Delete) • But what you create, what you select to

read or update or delete, is not necessarily simple


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://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/titles/programs/program_id

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






How about PayPal?


Some RESTful APIs with great docs ● Netflix

● Twitter

● Github

● Facebook

● PayPal

● Flickr

● Google


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


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


Important features of a good API

● Consistency ● Good error messages ● Clear naming conventions ● Just like for any other software product!


API standards?

● Very popular APIs tend to become de facto standards

● Standards include: REST, RPC, etc. ● REST is probably winning the day


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.


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!


Pet Store Swagger


Model in Swagger


Model

What goes in the POST box? { "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>"

}


Model by slug


Flickr API Garden Look what you can do:

https://www.flickr.com/services/api/explore/?method=flickr.photos.search


PayPal test environment

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

Presenter

Presentation Notes

Full testing environment helps a great deal. Note that usability and documentation of APIs tend to slide into each other.

https://developer.paypal.com/docs/classic/lifecycle/ug_sandbox/






API docs should include …

• Description • Tutorials • Examples (Snippets, working apps) • Sandbox test environment • FAQs

Presenter

Presentation Notes

Use snippets with care


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

Presenter

Presentation Notes

Twitterhttps://dev.twitter.com/docs/faq


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.

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


Backlinks

Twitter


Twitter API doc page

Presenter

Presentation Notes

Full testing environment helps a great deal. Note that usability and documentation of APIs tend to slide into each other.





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


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

Presenter

Presentation Notes

Get the developers to say what the API is going to do. Attend all relevant sprint meetings. Insist on what the examples will look like before it is created. Can you document the API before it fully exists? Start testing against it with the appropriate tool.


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.

Presenter

Presentation Notes



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!

Presenter

Presentation Notes



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!

http://jacobian.org/writing/what-to-write/

http://www.theparticlelab.com/good-api-documentation/

http://ffeathers.wordpress.com/




http://stackoverflow.com/questions/2001899/creating-great-api-documentation-tools-and-techniques

http://stackoverflow.com/questions/2001899/creating-great-api-documentation-tools-and-techniques

https://www.youtube.com/watch?v=C5ws9ZNUfxc

http://www.apiacademy.co




[email protected] @LoisRP

mailto:[email protected]

mailto:[email protected]

Lois Patterson - Learning how to document APIs by example; soapconf 2014

Technology

Transcript of Lois Patterson - Learning how to document APIs by example; soapconf 2014