Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

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

1,367 views

Published on

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.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

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

  1. 1. © 2014 - Proprietary and Confidential Information of FINCAD An example-based approach (by Lois Patterson) Creating Good API Documentation
  2. 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. 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. 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. 5. © 2014 - Proprietary and Confidential Information of FINCAD YouTube Embed Code
  6. 6. © 2014 - Proprietary and Confidential Information of FINCAD API to embed video (2)
  7. 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. 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. 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. 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. 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. 12. © 2014 - Proprietary and Confidential Information of FINCAD How about PayPal?
  13. 13. © 2014 - Proprietary and Confidential Information of FINCAD Some RESTful APIs with great docs ● Netflix ● Twitter ● Github ● Facebook ● PayPal ● Flickr ● Google
  14. 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. 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. 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. 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. 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. 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. 20. © 2014 - Proprietary and Confidential Information of FINCAD Pet Store Swagger
  21. 21. © 2014 - Proprietary and Confidential Information of FINCAD Pet Store Swagger
  22. 22. © 2014 - Proprietary and Confidential Information of FINCAD Model in Swagger
  23. 23. © 2014 - Proprietary and Confidential Information of FINCAD Model
  24. 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. 25. © 2014 - Proprietary and Confidential Information of FINCAD Model by slug
  26. 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. 27. © 2014 - Proprietary and Confidential Information of FINCAD PayPal test environment PayPal https://developer.paypal.com/docs/classic/lifecycle/ug_sandbox/
  28. 28. © 2014 - Proprietary and Confidential Information of FINCAD API docs should include … • Description • Tutorials • Examples (Snippets, working apps) • Sandbox test environment • FAQs
  29. 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. 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. 31. © 2014 - Proprietary and Confidential Information of FINCAD Backlinks Twitter
  32. 32. © 2014 - Proprietary and Confidential Information of FINCAD Twitter API doc page
  33. 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. 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. 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. 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. 37. © 2014 - Proprietary and Confidential Information of FINCAD
  38. 38. © 2014 - Proprietary and Confidential Information of FINCAD L.Patterson@fincad.com @LoisRP

×