Your API catalog is a fiction. Here is how to make it true.
Every enterprise we visit has an API catalog. It is usually a spreadsheet, occasionally a wiki page, and in ambitious cases a portal populated last autumn. It lists somewhere between forty and four hundred APIs, with owners, versions, and descriptions. It is also, invariably, wrong.
Not wrong through negligence, wrong the way any manually maintained mirror of a living system is wrong. Services shipped since the last update. Versions retired on paper still take traffic. Owners changed teams. The catalog describes the estate as someone remembered it, and estates do not stand still to be remembered.
Why the gap costs money
- Incidents: the API behind an outage is not in the catalog, so finding its owner burns the first hour.
- Security: the endpoints attackers find are precisely the ones nobody listed.
- Duplication: teams rebuild what they cannot discover, and the estate grows by copying itself.
- Audits: every compliance exercise begins with an inventory nobody trusts, so every exercise begins with archaeology.
A catalog maintained by hand is a description. A catalog derived from traffic is a fact.
Why manual catalogs are doomed by design
The instinct when a catalog falls out of date is to blame discipline: if only teams updated it when they shipped, it would be accurate. But this misunderstands the problem. A manual catalog is a copy of reality that must be kept in sync by human effort, and any copy maintained that way will diverge, because the incentive to update it is weakest exactly when the estate is changing fastest. The catalog is not out of date because people are careless; it is out of date because it is a copy, and copies rot.
There is a deeper irony. The APIs most likely to be missing from a hand-kept catalog are the ones that matter most for security and incidents: the ones stood up in a hurry, by someone under pressure, who had no time to update a spreadsheet. So the manual catalog is not merely incomplete, it is systematically incomplete in precisely the places you would most want it to be right. Its blind spots are not random; they line up with your risk.
Make the truth automatic
The only inventory that stays correct is one generated from the estate itself: what registers through the gateway exists, what takes traffic is alive, and what has served nothing for six months is a retirement candidate, with the data to prove it. The spreadsheet's job, knowing what you have, moves to infrastructure; humans keep the part they are good at, deciding what it all means.
Customers who make this shift report a curious side effect: the catalog stops being a compliance artifact and starts being used, by developers looking for what exists before building it again. That is the test of a true catalog. Fictions get audited; facts get read.