Because in the end, it’s not machines communicating with machines, at least not originally – it’s businesses communicating with businesses and people with people. APIs facilitate familiarity and help to eradicate the ‘us’ and ‘them’ boundaries in sharing resources and support, but that’s only possible with appropriate investment into documentation.
API communication is vulnerable to the same pitfalls as human communication. Misunderstandings are common. Parties need to exist on the same page – to be synced – and remain so as the API is updated. And there’s API scaling to consider – evolving communication overtime to suit a larger audience.
APIs are only as good as their documentation (which, in effect, becomes a communication manual). They’re tricky, with niggling idiosyncrasies that obstruct collaboration if not properly conveyed.
Effective and comprehensive API documentation covers the things that don’t make sense and which aren’t obvious to others. It saves time, and allows them to understand your inner workings. It enables users to understand results and API endpoints to take advantage of what’s available, and find the information they’re after. Even the best APIs aren’t worth a dime without documentation that clarifies means of access, how everything works, and how to derive value. Documentation requires investment – it can be a hassle, but it’s necessary for bridging businesses and offering the true value of your APIs.