STC Summit 2015: API Documentation, an Example-Based Approach
Download as PPTX, PDF13 likes2,244 views
The document discusses best practices for documenting APIs. It recommends including clear documentation of an API's functionality through descriptions, tutorials, code examples, and testing environments. Good API documentation demonstrates consistency in naming conventions and clear explanations of errors. The document provides examples of APIs with well-designed documentation, such as Netflix, Twitter, and GitHub, and encourages making APIs as simple and intuitive as possible for developers and non-developers alike.
Ad
More Related Content
What's hot (16)
Viewers also liked (6)
Ad
Similar to STC Summit 2015: API Documentation, an Example-Based Approach (20)
Ad
Recently uploaded (20)
![Download Wondershare Filmora Crack [2025] With Latest](https://cdn.slidesharecdn.com/ss_thumbnails/neo4j-howkgsareshapingthefutureofgenerativeaiatawssummitlondonapril2024-240426125209-2d9db05d-250419-250428115407-a04afffa-thumbnail.jpg?width=560&fit=bounds)
STC Summit 2015: API Documentation, an Example-Based Approach
- 1. © 2015 - Lois Patterson An example-based approach (by Lois Patterson) Creating Good API Documentation
- 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. © 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. © 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. © 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. © 2015 - Lois Patterson What is an API • Example: Many APIs together in one app
- 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. © 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. © 2015 - Lois Patterson YouTube Embed Code
- 10. © 2015 - Lois Patterson API to embed video
- 11. © 2015 - Lois Patterson (Flickr, user davenielsen) “The cloud”? IoT? Think APIs.
- 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. © 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. © 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. © 2015 - Lois Patterson Example: Multiple API Usage Twitter API, AlchemyAPI, Python language
- 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. © 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. © 2015 - Lois Patterson Example: Stripe API Docs
- 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. © 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. © 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. © 2015 - Lois Patterson REST APIs in a Nutshell • Verbs + nouns • Requests + responses • (And authentication and headers and other details)
- 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. © 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. © 2015 - Lois Patterson How about PayPal?
- 26. © 2015 - Lois Patterson Some RESTful APIs with great docs Netflix Twitter Github Facebook PayPal New York Times Google Stripe SoundCloud Amazon
- 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. © 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. © 2015 - Lois Patterson Important features of a good API • Consistency • Good error messages • Clear naming conventions • Just like for any other software product!
- 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. © 2015 - Lois Patterson API success • Want mass-market adoption? • Think Simple.
- 32. © 2015 - Lois Patterson What does an API look like? • Not just code • You can visualize APIs
- 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. © 2015 - Lois Patterson New York Times Example
- 35. © 2015 - Lois Patterson New York Times Example
- 36. © 2015 - Lois Patterson Pet Store Swagger
- 37. © 2015 - Lois Patterson Pet Store Swagger
- 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. © 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. © 2015 - Lois Patterson Your first application
- 41. © 2015 - Lois Patterson PayPal test environment PayPal https://developer.paypal.com/docs/classic/lifecycle/ug_sandbox/
- 42. © 2015 - Lois Patterson API docs should include … • Description • Tutorials • Examples (Snippets, working apps) • Sandbox test environment • FAQs
- 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. © 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. © 2015 - Lois Patterson Twitter API doc page
- 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. © 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. © 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. © 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. © 2015 - Lois Patterson Enjoy documenting APIs! • Lots of energy and opportunity in this field • Always a chance to learn something new
- 51. © 2015 - Lois Patterson
- 52. © 2015 - Lois Patterson [email protected] @LoisRP