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.

API Documentation Best Practices

2,417 views

Published on

Documentation is a critical component of any API. But it goes beyond just explaining the API into understanding who your users are, what their use cases are, and then working to make their journey as simple as possible - while accounting for different learning styles.

Published in: Technology

API Documentation Best Practices

  1. 1. l All contents Copyright © 2014, MuleSoft Inc. API Documentation Best Practices by mike stowe
  2. 2. l All contents Copyright © 2014, MuleSoft Inc. • API Fanatic • Open Source Contributor • Author, Speaker, Consultant • 10+ years hacking Professional Code • Dev Relations Manager at MuleSoft About Me @mikegstowe
  3. 3. l All contents Copyright © 2014, MuleSoft Inc. API Documentation is a critical component to the usability of your API – and thus critical to its success
  4. 4. l All contents Copyright © 2014, MuleSoft Inc. Understanding your users is critical to creating good documentation.
  5. 5. l All contents Copyright © 2014, MuleSoft Inc.5 • Who is your API Documentation for? - Is it to be used internally ∙ Limited technologies? ∙ Uniform expertise? - Is it to be used externally ∙ Multiple technologies ∙ Wide variety of skill levels Document with a Purpose
  6. 6. l All contents Copyright © 2014, MuleSoft Inc.6 • Why should they be using your API? - What functionality does your API provide • Why shouldn’t they be using your API? - What are the limitations of your API Document with a Purpose
  7. 7. l All contents Copyright © 2014, MuleSoft Inc.7 • What are their use cases? - How are they using your API - What measures are critical to their success - What unique workarounds or hiccups might they experience when using that use case - What are the best practices for that use case Document with a Purpose
  8. 8. l All contents Copyright © 2014, MuleSoft Inc.8 • How can you create the easiest onboarding process for your users? - What do they need to get started in 5 minutes - What are the dependencies or other technologies they need to understand to use your API - What complications might they face - What issues might they need to debug Document with a Purpose
  9. 9. l All contents Copyright © 2014, MuleSoft Inc. Documentation isn’t about your API… it’s about your users.
  10. 10. l All contents Copyright © 2014, MuleSoft Inc. This means your API documentation must be reliable.
  11. 11. l All contents Copyright © 2014, MuleSoft Inc.11 • Who is responsible for maintaining your documentation? - Do you have technical writers and engineers working on your docs - Are you using code-first or spec driven development - What quality measures do you have to ensure your docs and API stay in sync Have a Plan
  12. 12. l All contents Copyright © 2014, MuleSoft Inc.12 1. API is designed and user tested using RAML 2. Technical Writers modify descriptions in RAML, add in missing doc components 3. Tests are generated from RAML spec 4. Engineers code to tests, API is QA’d 5. Code pushed, RAML pushed to documentation site Sample Plan Outline when using Spec Driven Development
  13. 13. l All contents Copyright © 2014, MuleSoft Inc.13 • Make it a priority for engineers and technical writers to be communicating throughout the documentation process (including “real-life” documentation QA) • Make it a priority for engineers to document changes they make as they go • Make sure technical writers are aware of backward compatibility breaks, format changes • Hope for the best If not using Spec Driven Development
  14. 14. l All contents Copyright © 2014, MuleSoft Inc. Out of sync documentation isn’t only not useful, but detrimental to the usability of your API.
  15. 15. l All contents Copyright © 2014, MuleSoft Inc. Just as important as reliability is readability.
  16. 16. l All contents Copyright © 2014, MuleSoft Inc. API documentation should be clear and concise.
  17. 17. l All contents Copyright © 2014, MuleSoft Inc.17 • Clear, easy path for users to use your API Good Documentation Provides:
  18. 18. l All contents Copyright © 2014, MuleSoft Inc.18 • Easy, one click navigation to important information Good Documentation Provides:
  19. 19. l All contents Copyright © 2014, MuleSoft Inc.19 • Clear explanations of resource/ method functionality Good Documentation Provides:
  20. 20. l All contents Copyright © 2014, MuleSoft Inc.20 • Callouts to important information developers should be aware of (including info boxes, alerts, and warnings) Good Documentation Provides:
  21. 21. l All contents Copyright © 2014, MuleSoft Inc.21 • List of available parameters for the method, including description, whether or not it is required, default value, example value, and any pattern or format requirements. Good Documentation Provides:
  22. 22. l All contents Copyright © 2014, MuleSoft Inc.22 • Sample calls with the correlating content types (ie what the call looks like when using JSON, XML, etc) Good Documentation Provides:
  23. 23. l All contents Copyright © 2014, MuleSoft Inc.23 • Sample responses for each content type Good Documentation Provides:
  24. 24. l All contents Copyright © 2014, MuleSoft Inc.24 • Code examples for the languages most commonly used by your users (ie a public API might showcase JavaScript, PHP, Ruby, Java, and .NET) Good Documentation Provides:
  25. 25. l All contents Copyright © 2014, MuleSoft Inc.25 • Sample use-case/ walk-though of the API method Good Documentation Provides:
  26. 26. l All contents Copyright © 2014, MuleSoft Inc.26 • Ability to try API calls in real-time/ interactive API debugging Good Documentation Provides:
  27. 27. l All contents Copyright © 2014, MuleSoft Inc.27 • List of error HTTP status codes and reason(s) that code may be returned Good Documentation Provides:
  28. 28. l All contents Copyright © 2014, MuleSoft Inc.28 • Or if you use custom error codes (ie an error code within the body of the error response) Good Documentation Provides:
  29. 29. l All contents Copyright © 2014, MuleSoft Inc.29 • Information on/ links to appropriate SDKs/ code libraries Good Documentation Provides:
  30. 30. l All contents Copyright © 2014, MuleSoft Inc.30 • Frequently Asked Questions with answers (including code examples or links to tutorials) Good Documentation Provides:
  31. 31. l All contents Copyright © 2014, MuleSoft Inc.31 • Links to additional resources/ learning tools • Comments section for group discussion • Links to support mechanisms (forum, knowledge base, contact form, etc) Good Documentation Provides:
  32. 32. l All contents Copyright © 2014, MuleSoft Inc. Your documentation should be so easy to use that a developer with no experience can implement your API in less than 5 minutes.
  33. 33. l All contents Copyright © 2014, MuleSoft Inc.33 • Shopify • Spotify • Constant Contact • Twilio • Stripe • SendGrid • DropBox • MuleSoft Champions Examples of Great API Documentation
  34. 34. l All contents Copyright © 2014, MuleSoft Inc.34 • mulesoft.com/restbook – book on API design and documentation (presentation from Chapter 12) • Idratherbewriting.com – technical writing blog • bit.ly/raml4doc – presentation on using RAML for documentation • bit.ly/githubmd – GitHub’s guide to markdown (used for Anypoint Platform documentation) More Resources
  35. 35. l All contents Copyright © 2014, MuleSoft Inc. THANK YOU!!! mulesoft.com/restbook
  36. 36. l All contents Copyright © 2014, MuleSoft Inc. @MuleDev mulesoft.com/restbook

×