API Documentation Best Practices

l All contents Copyright © 2014, MuleSoft Inc.

API DocumentationBest Practices

by mike stowe


• API Fanatic

• Open Source Contributor

• Author, Speaker, Consultant

• 10+ years hacking Professional Code

• Dev Relations Manager at MuleSoft

About Me

@mikegstowe


API Documentation is a critical component to the usability of your API – and thus critical to its success


Understanding your users is critical to creating good documentation.

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


• 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



• 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



• 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



Documentation isn’t about your API… it’s about your users.


This means your API documentation must be reliable.


• 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


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


• 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


Out of sync documentation isn’t only not useful, but detrimental to the usability of your API.


Just as important as reliability is readability.


API documentation should be clear and concise.


• Clear, easy path for users to use your API

Good Documentation Provides:


• Easy, one click navigation to important information



• Clear explanations of resource/ method functionality



• Callouts to important information developers should be aware of (including info boxes, alerts, and warnings)



• 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.



• Sample calls with the correlating content types (ie what the call looks like when using JSON, XML, etc)



• Sample responses for each content type



• Code examples for the languages most commonly used by your users (ie a public API might showcase JavaScript, PHP, Ruby, Java, and .NET)



• Sample use-case/ walk-though of the API method



• Ability to try API calls in real-time/ interactive API debugging



• List of error HTTP status codes and reason(s) that code may be returned



• Or if you use custom error codes (ie an error code within the body of the error response)



• Information on/ links to appropriate SDKs/ code libraries



• Frequently Asked Questions with answers (including code examples or links to tutorials)



• Links to additional resources/ learning tools

• Comments section for group discussion

• Links to support mechanisms (forum, knowledge base, contact form, etc)



Your documentation should be so easy to use that a developer with no experience can implement your API in less than 5 minutes.


• Shopify

• Spotify

• Constant Contact

• Twilio

• Stripe

• SendGrid

• DropBox

• MuleSoft Champions

Examples of Great API Documentation


• 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


THANK YOU!!!mulesoft.com/restbook


@MuleDevmulesoft.com/restbook

Technology

API Documentation Best Practices