O slideshow foi denunciado.
Utilizamos seu perfil e dados de atividades no LinkedIn para personalizar e exibir anúncios mais relevantes. Altere suas preferências de anúncios quando desejar.

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

1.949 visualizações

Publicada em

Publicada em: Software
  • Seja o primeiro a comentar

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

×