In the future, when self-descriptive hypermedia web APIs have taken over the world, we probably won’t need to write out-of-band human-readable documentation anymore.
But we are not there yet.
For now, writing documentation is still a fundamental part of publishing a web API - and your API will only looks as good as your documentation makes it. That’s why I want to share with you 10 ways to create a documentation that is easy to use for developers.
Most of the rules are common sense, but it’s easy to forget some of them.
1. Document all resources
Your entire API should be documented. That means all the developers-facing resources should have clear instructions about their use.
2. Keep your documentation up-to-date
If you don’t follow this rule, there is no point following the others. A documentation that is not up-to-date is pointless, and will only cause frustrations for your users.
Always ensure that new features or changes get documented. This can be made automatic or, just like automated tests, can be a requirement for any pull request. You wouldn’t create a pull request without tests, right?
3. Provide copy/paste examples
Developers like to test before they implement something. Offering an easy way to copy/paste curl requests is a good way of doing that. If developers are logged in, you can even include their API key directly in the documentation making it even easier for them to test your endpoints.
Other tools, like Swagger and Swagger UI integrate that feature in a web page and make it simple to send HTTP requests (as long as your API allows CORS requests).
4. Show expected responses
Developers should be capable of understanding the request flow based only on your documentation. Theoretically, they should even be able to implement a client for your API without actually making any request. This means you need to show them what is the expected output for each documented request.
5. Provide a “Getting Started” guide
The documentation for your API is going to be a great reference for all the features it comes with. Sadly, it’s easy to feel overwhelmed without a simple tutorial to get started.
A “Getting Started” guide should be available for your API to, at the very least, show how to get an API key, write the first request and get a response back.
6. Put yourself in the developer’s shoes
When you’re building a web API, you usually build for other people, not for yourself (of course, there are exceptions). Well, put yourself in someone else’s shoes, forget everything you know about the API and try to make some requests using only the documentation you wrote.
7. Validate your documentation before releasing it
The previous rule is only good to a certain extent. You can do your best to pretend that you don’t know anything about the API, but there’s going to be some stuff that you will miss. Even something you might think is common knowledge could cause a lot of frustration for implementers.
To validate your API, take a pool of developers and make them read the documentation. They should be able to understand how everything is structured using only the documentation, and without asking you any clarifying questions. Ask them to create a small program accessing one resource and do something with the result as a test.
Improve the documentation based on their feedback.
8. Create SDKs for your API
SDKs allow you to abstract the communication with your API, hiding the complexity and the HTTP calls so developers can simply use their favorite programming language to talk with your service.
9. Communicate with your API users
Developers rely on your API and expect it to simply work. If something breaks, they need to know ASAP. That’s your responsibility to tell them when something goes wrong or when changes are coming.
You can let your community know what’s happening using a blog, a newsletter, a changelog or a combination of the three.
If you open your API to a lot of people, you should also have a place for them to chat about it, ask for help, suggest features, give feedback and report bugs. This kind of platform will help you improve your API and make it better using your users’ ideas.
10. Set up a status page
One day, your API will go down for some unknown reason. When it happens, people who rely on it need to know that there is something wrong on your side and that you’re working on fixing it.
A status page is the perfect way to accomplish both of these objectives.
Wrap Up
To go with the great documentation you created, you need to have an awesome web API running in the back. If Ruby is your favorite language to create this kind of application, you will probably be interested by the book I wrote: Master Ruby Web APIs. I just released it and it’s 20$ Off until July, 20. Don’t miss out!
