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.

STC Summit 2015: API Documentation, an Example-Based Approach

2,096 views

Published on

Published in: Software
  • Login to see the comments

STC Summit 2015: API Documentation, an Example-Based Approach

  1. 1. © 2015 - Lois Patterson An example-based approach (by Lois Patterson) Creating Good API Documentation
  2. 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. 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. 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. 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. 6. © 2015 - Lois Patterson What is an API • Example: Many APIs together in one app
  7. 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. 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. 9. © 2015 - Lois Patterson YouTube Embed Code
  10. 10. © 2015 - Lois Patterson API to embed video
  11. 11. © 2015 - Lois Patterson (Flickr, user davenielsen) “The cloud”? IoT? Think APIs.
  12. 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. 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. 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. 15. © 2015 - Lois Patterson Example: Multiple API Usage Twitter API, AlchemyAPI, Python language
  16. 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. 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. 18. © 2015 - Lois Patterson Example: Stripe API Docs
  19. 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. 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. 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. 22. © 2015 - Lois Patterson REST APIs in a Nutshell • Verbs + nouns • Requests + responses • (And authentication and headers and other details)
  23. 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. 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. 25. © 2015 - Lois Patterson How about PayPal?
  26. 26. © 2015 - Lois Patterson Some RESTful APIs with great docs Netflix Twitter Github Facebook PayPal New York Times Google Stripe SoundCloud Amazon
  27. 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. 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. 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. 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. 31. © 2015 - Lois Patterson API success • Want mass-market adoption? • Think Simple.
  32. 32. © 2015 - Lois Patterson What does an API look like? • Not just code • You can visualize APIs
  33. 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. 34. © 2015 - Lois Patterson New York Times Example
  35. 35. © 2015 - Lois Patterson New York Times Example
  36. 36. © 2015 - Lois Patterson Pet Store Swagger
  37. 37. © 2015 - Lois Patterson Pet Store Swagger
  38. 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. 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. 40. © 2015 - Lois Patterson Your first application
  41. 41. © 2015 - Lois Patterson PayPal test environment PayPal https://developer.paypal.com/docs/classic/lifecycle/ug_sandbox/
  42. 42. © 2015 - Lois Patterson API docs should include … • Description • Tutorials • Examples (Snippets, working apps) • Sandbox test environment • FAQs
  43. 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. 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. 45. © 2015 - Lois Patterson Twitter API doc page
  46. 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. 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. 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. 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. 50. © 2015 - Lois Patterson Enjoy documenting APIs! • Lots of energy and opportunity in this field • Always a chance to learn something new
  51. 51. © 2015 - Lois Patterson
  52. 52. © 2015 - Lois Patterson L.Patterson@fincad.com @LoisRP

×