API Documentation

Programs often need to work together with other programs. A weather app, for example, fetches its forecast from a weather service. For this to work, the foreign service provides a fixed connection point: a programming interface, or API for short. There, it is precisely defined which requests are allowed and what comes back. API documentation is the text that describes all of this. It is thus the instruction manual for developers who want to use the service — comparable to a menu that lists what you can order and what you get for it.

Why bad docs cost money

An interface can be technically perfect and still no one uses it. If there’s no description of how to address it, it remains unusable. Experience shows that developers decide within a few minutes whether to try out a service or go to a competitor. They spend these minutes in the documentation, not in a sales conversation.

For companies, this is therefore an economic issue. Payment providers like Stripe or cloud providers sell their services almost exclusively through interfaces. Their documentation is the actual product surface. If a piece of information is missing, the questions end up in support, and every call costs work time.

A second point is reliability. The documentation is also a promise: what’s written there should still hold true tomorrow. If a provider changes its interface without notice, programs break for all customers at the same time. Good providers therefore also document what changed and when.

What’s in good API docs

The core is formed by the reference. It lists every single function that can be called. For each function, this includes the information that must be sent along, and a description of what comes back. In addition, there’s the list of error messages, since a program must also be able to handle rejections.

Pure reference lists aren’t enough, though. That’s why there is usually an introductory chapter that leads step by step to the first working call. Registration is also important: almost every interface requires a personal access key, so the provider knows who is making the request and whom to bill for usage. Limits also belong here, such as the maximum allowed number of requests per minute.

Much of this is now created semi-automatically today. Developers describe their interface in a standardized file, often following the OpenAPI format. A tool then generates the reference pages, including sample code, from this description. The advantage: if the interface changes, the documentation changes along with it. Explanatory texts and examples, however, still have to be written by a human.

From hobby projects to ChatGPT plugins

You encounter API documentation everywhere services are combined. Anyone building a school project with railway timetable data reads its docs. Anyone programming a Discord bot does too. These pages are often simply called “Docs” or “Developers” and can be reached via a website’s footer.

In the AI industry, the topic has gained additional weight. Providers like OpenAI or Anthropic sell access to their language models exclusively through interfaces. How much a request costs, how long the text is allowed to be, what settings exist — all of this is in the documentation. When news talks about a new model, the technical details are often found there first.

What’s new is that these texts are now also being read by programs themselves. AI assistants are fed interface descriptions in order to write program code from them or call services independently. Clean, machine-readable documentation is therefore doubly valuable. A common misconception, by the way, is confusing API documentation with user manuals: manuals are aimed at people in front of an interface, API documentation at people who write code.