Engineering leaders cannot see their own API landscape

A VP of Engineering is in a planning meeting when someone asks a question that should be easy. How many APIs do we have, and which of them are in bad shape? The VP does not know. Nobody in the room knows. What happens next is a two-week exercise: a spreadsheet goes round, every team self-reports its own APIs when they get to it, half the rows are stale by the time the thing is compiled, and it produces a number at the end that everyone in the room quietly understands to be approximate.

The question was not exotic. It was the API equivalent of “how many people work here” or “what did we spend last quarter”, and for those the VP has an exact answer on a screen, sourced from a system that is correct because the business runs on it. For the APIs, the most strategic layer they own, the contracts the whole company integrates against, the answer required a small project and came back fuzzy. A leader who can see their headcount to the person and their spend to the dollar cannot see their API estate at all.

The estate never got a system of record

The reason this persists is that APIs are produced decentrally and never rolled up anywhere that stays current.

Every team builds and changes its own APIs, on its own schedule, in its own repositories. Each team knows its own corner. Nobody holds the whole, because there is no place the whole assembles as a byproduct of the work. The information is not secret; it is scattered, across repositories, gateways, wikis, and the memories of the people who built each piece. Leadership dashboards exist for the things that already have a system of record: finance has one, so spend is visible; HR has one, so headcount is visible; the ticketing tool has one, so incidents are visible. The API estate never got a system of record, so it never got a view, and you cannot put on a dashboard a fact that nothing is keeping true.

The result is an asymmetry that is genuinely strange when you say it out loud. The layer that is most strategic, the contracts the business depends on, is the layer leadership can see least.

The tax is mostly paid upward

For the engineers, the day-to-day cost is the survey. Every time leadership needs to know the shape of the estate, work stops while teams re-enter the same facts into another spreadsheet, and those facts are stale again by the next quarter, so the survey is not a one-off but a recurring tax with no accruing benefit. The map is redrawn from scratch each time and thrown away.

But the real weight of this one lands on the people who answer for the estate, which is why it is worth treating as a leadership problem rather than an engineering annoyance.

You are making decisions about a landscape you cannot see. Which APIs to invest in and which to retire, where the coupling risk sits, whether the team you are about to lose takes critical knowledge with them, how much of your surface a reorganisation would strand: all of it is decided on intuition and a few phone calls, because there is no view to decide it from. A new leader inheriting the group spends months assembling a mental model by asking who owns what, and that model lives in their head and leaves when they do. Governance is unmeasurable, because “are our APIs healthy” has no number attached to it. Risk is invisible, because the one load-bearing, undocumented, un-owned API is exactly the one no survey surfaced. You are accountable for an estate you can only perceive through anecdote.

sequenceDiagram
    participant L as VP Engineering
    participant T as Every team
    participant S as Spreadsheet
    L->>T: how many APIs, and which are healthy?
    T->>S: self-report, when they get to it
    Note over S: half the rows stale by the time it compiles
    S-->>L: an approximate number, two weeks later
    Note over L,S: next quarter, run the whole exercise again

The asymmetry, in numbers you already have

You do not need a fabricated statistic to feel this. Picture an organisation with dozens of teams and a few hundred APIs. The leader’s working model of that estate is, realistically, whatever surfaced in the last incident plus whatever they happen to remember. Now put that next to what the same leader can see about spend: a line per team, to the dollar, updated continuously, without asking anyone.

The point is the gap between those two. The financial layer has a system of record, so it has a view. The contract layer, which is arguably more central to how the business actually works, has neither. The most important thing to be able to see is the thing built with the least visibility, and the reason is not that anyone decided it should be invisible. It is that nobody ever gave it a place to be seen.

Why the obvious tools do not add up to a view

There are tools in this space, and each shows a slice while leaving the leadership question unanswered.

Spreadsheets and surveys are the baseline, and they are manual, self-reported and stale, which is the whole problem restated as a process.

Service catalogues, Backstage and its kin, can aggregate, but only to the extent that every team maintains its entries, so coverage is partial by construction, and they hold names and ownership rather than health. A catalogue can tell you an API exists. It rarely tells you whether it is any good.

Observability and BI dashboards show the runtime, latency, error rates, spend, which is real and valuable and about the wrong layer. They tell you an API is slow. They do not tell you it is undocumented, that it shipped a breaking change last week, or that it has no owner. Health of the contract is not the same as health of the traffic.

Gateways see what flows through them, by route, for the traffic that passes through them, which is neither complete coverage nor a rollup to teams and health.

None of these turns the contract-layer facts, how many, whose, how healthy, how coupled, into something a leader can read without commissioning a project.

What would have to be true

Argue it from the properties.

The estate needs a system of record that is current as a byproduct of normal work. If the count comes from specs published as part of shipping, rather than from a survey, then the count is real and it is today’s, not last quarter’s approximation.

Health has to be a measured signal, not a vibe. Governance results, lint quality, breaking-change history, readiness for the things that consume the API: those give “healthy” a number that can move, which is the difference between a metric and an opinion.

It has to roll up to the units a leader reasons in, teams and domains, so the view answers “which part of my organisation is carrying risk” rather than dumping a flat list of endpoints.

It needs the coupling view, who depends on whom, to price risk at all, and this is the hard part, because that dependency graph is exactly the thing organisations do not have. Without it, “what breaks if this team leaves” stays unanswerable.

And it has to be a read a leader can get on demand, not a project they commission each time the question comes up.

graph TD
    CI["Specs published from CI"] --> REG["Registry: system of record"]
    GOV["Governance + readiness checks"] --> REG
    REG --> VIEW["Org landscape view"]
    VIEW --> M1["How many, and whose"]
    VIEW --> M2["Health per team"]
    VIEW --> M3["Breaking changes, adoption"]
    VIEW -. still being built .-> M4["Coupling and blast-radius risk"]

How we come at it

Full disclosure: this is the spec0 blog, so read this as interested rather than neutral, and read it precisely, because the honest answer here is half-built.

What exists today is the rollup. Because specs are published to a registry from CI and governance runs against them, spec0 can turn the scattered facts into an org-level view: how many APIs there are and which teams own them, governance and health broken down per team, breaking changes over time, and how much your agents actually use each API. The count and the health stop being a survey and become a screen, sourced from the same act of shipping that produces the APIs in the first place.

What does not exist yet is the hardest and most valuable panel: the full coupling and blast-radius view, who depends on whom across the whole estate, so a leader can price the risk of a change or a departure. That rests on the consumer graph, which is being laid rather than finished, and I would rather name the gap than let a rollup of coverage and health imply a map of risk we have not completed. The landscape you can see today is real. The part that tells you what is dangerous is still coming.

The part worth arguing about

A landscape view is only ever as honest as its coverage, and that is the uncomfortable thing about building one. It shows you what is in the registry, which means the most dangerous API in the company might be the precise one that never got registered: the shadow service someone stood up in a hurry, the legacy job that has run on a cron since before anyone in the room joined. A dashboard that reads one hundred percent healthy is telling you about the estate it can see, and the failure mode of a clean dashboard is false confidence.

flowchart TD
    V["Landscape view: 100% healthy"] --> Q{Of what?}
    Q -->|the registered APIs| SEEN["The estate you can see"]
    Q -->|the shadow service on a cron| UNSEEN["The estate nobody registered"]

So the question I keep coming back to is whether a leadership view that is loud about its own blind spots is more useful than one that looks complete. A number that says “eighty percent of what we know about is healthy, and we suspect we know about seventy percent of it” is less satisfying and much more honest than a confident green. If you have run an estate view that measured its own coverage, rather than quietly assuming it was total, I would like to know how you estimated the part you could not see.