The user interface of an application – even one with a convoluted design – gives users some sense about how to navigate the application. It may be painful, but users can usually muddle through if they have to. APIs, on the other hand, offer no natural affordances or signifiers allowing developers to learn how to use the API. Therefore, good documentation is crucial for any API project.
The First Step is Designing an Effective API
Just as with your software’s user interface, good API usability is the first key to good API documentation. Even the best documentation can’t cover up for poor design choices. If your methods are named inconsistently, data returned for the same object type varies from method to method, errors are unclear and unhelpful, etc., great documentation won’t turn a bad API into a good one.
For more information, API management company Apigee has prepared a great white paper on API design.
(And for goodness sake, when using a SOAP API, keep your WSDL files up to date!)
Presentation
API documentation is best presented as HTML accessible via a developer portal site.
The presentation should be clean, simple, and consistent. Request parameters should be presented the same way every time. Same for response parameters, sample requests/responses, code samples, etc. Use headings to make the document easy to scan. Use styles to differentiate code samples, methods, fields, etc.
Some tools that can be used to generate API documentation:
• Sphinx – A popular tool to generate HTML and PDF output, built to generate the documentation for the Python language.
• Help authoring tools – We use MadCap Flare because of its powerful capabilities in reusing content and generating output in multiple formats.
• Swagger – Offers a tool for building simple, interactive API documentation.
• Build your own – Great front-end frameworks like Bootstrap or Foundation make it easy.
When Should I Use a PDF?
Here’s a list of situations when providing your API documentation as a PDF is a good idea:
• Never
• Never ever
• Please don’t ever do this
• Thursdays
• Just kidding; I meant never, ever, ever do this
Basics
Some integrators are just going to jump right in, start playing with the code, and maybe dig around the reference. Other integrators are going to need an overview and some type of walkthrough to help them get started.
In the overview you should cover:
• What your API does, how it works, who it’s for, what you can do with it
• Basic rules and conventions your API follows
• Base URLs, formats supported
• Authentication
Walkthroughs are helpful for integrators to find where to start and get their feet wet using your API. A couple of ways to use a walkthrough:
• Flow chart of the integration process when calls need to be made in a specific order
• Some type of tutorial to build a sample application or the initial components to start
Working with your integration supporters is a great way to figure out what types of information should be included in overviews and walkthroughs. They’ll know what developers have the hardest time understanding.
Examples
Examples are the technical writer’s secret sauce. Explain it. Show it.
Good API doc should come with example requests and responses for typical usage scenarios. It’s also a good idea to include examples for any particularly tricky usage scenarios (although, see Step 1, above).
Look how Stripe’s documentation provides example requests and responses right alongside method descriptions.
And, now that we live in the future, it’s even possible to provide API docs that let you execute sample code straight from the documentation page. Check out this example at Mandrill’s API documentation page:
There are a couple of open source tools that make this easy:
Mashery’s IO Docs is one and the project is available as an open source node.js application. Swagger, which I mentioned above, also provides the ability to set up interactive documentation.
Reference
The reference is the meat of the API document. This is where developers need to go to clarify specific questions about whatever method they are using. The reference needs to be complete and cover all of your public API. For each method, the reference should cover:
• What does each method do and when should you use it
• Method names and endpoints
• HTTP verbs to use, as applicable
• Whether request parameters are sent as URL parameters, POST parameters, or attached in the message as XML, JSON, etc.
For each of the parameters, the reference should cover:
• Name
• Whether or when it’s required
• Cardinality
• Data type accepted
• Allowed/enumerated values
• Any additional validation on the data that the integrators must know
For responses, the reference should cover:
• HTTP response codes
• Format of the response, JSON, XML, etc.
• When each response parameter is returned
• The data types/enumerated values for each response parameter
Conclusion
Inadequate API documentation is one of the biggest pain points developers face. It also leads to increased costs and wasted time on integration support. By covering the basics thoroughly and consistently, you can improve your developer experience, giving you happier integrators and reduced support costs.