Why API documentation matters
🏠The everyday picture
A railway timetable lets thousands of people plan journeys without phoning the station. If it's wrong, people miss trains, and they stop trusting it.
📘What it really is
- An API is only as useful as people's ability to understand it. Good documentation answers:
- what endpoints exist, and what each does;
- what to send (parameters, body, headers) and what comes back;
- how to authenticate;
- what errors can happen, and what they mean;
- limits (rate, size, pagination);
-
examples that work.
-
Your audiences: your own frontend (and future you), other developers, partners, and increasingly AI agents and tools that read API descriptions to call them.
-
Docs written by hand drift from the code. The goal is a single, machine-readable description that is checked against the real API (Lesson 5).
-
The industry standard for describing REST APIs is OpenAPI (formerly called Swagger).
🖱️Try it
Open the documentation of a public API you've heard of (Razorpay, GitHub or OpenWeather). Find: how to authenticate, one endpoint's parameters, an example response, the error format and the rate limits. Note what made it easy or hard to use.
✅Quick check
What's the main risk with documentation written separately by hand?
Show the answer
It drifts out of date as the code changes, until nobody trusts it.
Who reads API descriptions besides human developers?
Show the answer
Tools: code generators, testing tools, and AI agents that call APIs.