API documentation is the technical documentation of an API. It usually includes everything from what types the API supports to which endpoints exist and what they do. The documentation is essential in a few ways:

• Any developer who wants to use an API will need this document to know how exactly it works and can they trust it?
• New team members should be able to understand the operations behind an API without needing any extra research or conversations with team experts
• Users of an API will require this documentation to understand if the API is helpful for what they need.
• The documentation should be simple enough to read and understand in its own right

Photo by Sigmund on Unsplash

There are two types of documentation:

- API description guides: This is the documentation for each endpoint, and the format used is a simple table. The table includes the endpoint’s name, what parameters it takes, what type it’s off, and any other available options. This typically contains just about everything a developer would need to know about an API.

- API reference guides: This is more of an outline for each method or endpoint. Each one has a brief description along with any additional information. Some developers like to use this type of documentation because it’s easier to work with than the more simplified version, but both can be useful depending on how you plan to use them.

Note: API documentation is not reference documentation.

Photo by Christopher Gower on Unsplash

Let’s go through some of the tips in formulating API documentation.

The first tip is to keep it simple. Using chat speak or overly long sentences may look good, but they don’t explain anything. It may make more sense to put yourself in the shoes of a person who has no idea about the API — if you were doing that, my bet is you’d want things simplified and transparent as possible.

The more complicated the API, the more important this document is. If there’s many endpoints, complex types, and numerous routes, it’s essential that developers easily understand how things work without asking anyone else. It should be written in clear, simple language so even people with minimal technical experience can understand it and do not have to spend hours figuring it out.

Photo by Joshua Sortino on Unsplash

API documentation is also a form of technical writing that involves documenting code or programming languages capable of being used by other applications.

When writing a document for an API, make sure to include:

• Types supported. For example, if your API takes two parameters, both of which must be numbers, then make this clear in the documentation. It’s easy to mess up simple things like this and end up with documentation that people can’t understand.
• What requests are possible? For example, if all endpoints are GET requests and it’s impossible to POST anything, say so in the documentation. This helps developers trying to use the API know what they can do with it or what they need to learn before they start using it. In some cases like this, mentioning why other types aren’t allowed is practical as well.
• Which types are supported. If an API only takes emails and phone numbers as inputs, then say so. Make it clear what cannot be used to meet the requirements of the API.
• What can be done with those inputs? Fetch a list of users, load a specific user, or handle an error when something goes wrong. Are there any specific error codes that can be returned? This information should be easy to find in the documentation, so developers know how to use your API correctly and don’t have to get frustrated.

A good API document should be easy to reference but still maintain a straightforward and easy to read narrative. Your API documentation is a UI to customers. It’s the best way to market your end users, so develop with care.