Importance of documenting your API
The subject we’ll talk today is about API documentation and its importance.
Since we started thinking about services in SOA until now, the age of micro and nanoservices, we are distributing our systems each time more.
The more we distribute, more we need to clarify all the details of our endpoints, contracts, validations, etc, because someone will have to consume it.
I’ve seen, in many projects, people keeping documentation aside. We have contracts with lots of details and we need to expose it to our consumers.
Any time I’m writing a code and I need to consume an API that doesn’t belong to me or my team, I get crazy because the documentation is so poor (when it exists) and you need to guess things or talk to the person responsible. And you know, as much as me, that communication is an issue with a lot of people. After all, you end up wasting a lot of your time because the API doesn’t have a proper documentation.
API documentation is not only for our consumers. It also helps new team members, keep it in mind.
I’ll give some tips about things we could document that would make our consumers happy :).
Describe the different endpoints: what does a /orders endpoint mean? What’s the impact? Which are the dependencies?
Describe HTTP methods allowed on each endpoint: which HTTP methods can I use in each endpoint? What’s the effect?
Describe input/output fields: it’s very useful to have a good description of input fields, example:
Examplify the requests: having examples of how to make a call if a good thing that will save a lot consumer’s time. Putting information like method HTTP, URI and payloads helps a lot:
Examplify the responses: having examples of how the responses will be returned is also helpful. Putting information like status HTTP and response payloads helps a lot:
Describe every response status: response status is something important, so it also should be very clear on your API documentation. What status is shown in each case?
Describe versions: this is a very important point. API’s contract break and new versions are required. We need to have it clear on our documentation for each new version. I’d focus on major version changes (see more on semantic versioning here), that are the ones that really really matter. In a perfect world we’d have each minor/patch versions documented but that’s a lot.
Ah, but my API has swagger “documentation”.
Swagger helps a bit, but … does it include all these details? Is it so helpful?
I believe a complete documentation is important for everyone: consumers, new team members, bug fixes and so on.
In a perfect world, the things I described above are important to have a very complete documentation.
If I forgot something, feel free to add on the comments.