An orphaned API endpoint is a live endpoint that no team has said it depends on. A second gap usually travels with it: an endpoint with no owner, so nobody answers for it. The first means a change there warns nobody. The second means nobody is there to ask.
You can find both by comparing the endpoints in your OpenAPI specs with two lists, consumers and owners, and clear them with a short weekly review. We build Graphwake, which tells the teams that consume an API when a change in its OpenAPI spec is about to break them, and an orphan is exactly the endpoint where it has nobody to tell. Here's how we'd find them by hand, and then how Graphwake does it for you.
Two gaps, two questions
| Gap | The question it leaves open | What goes wrong |
|---|---|---|
| No consumer team on record (orphan) | Whom do we tell when this endpoint changes? | A breaking change ships and the team that calls it hears from its users first |
| No owner | Whom do we ask about this endpoint? | Questions, incidents and retirement decisions have nobody to go to |
The two are independent. An endpoint can have an owner and no known consumers, which is the common case for a new endpoint. It can have five consumer teams and no owner, which is common after a reorganisation. Both are worth a look, and they need different fixes.
A note on the word. In API security writing, "orphaned", "zombie" and "shadow" APIs are endpoints that stay reachable while nobody maintains or owns them, and tools find them from traffic: Cloudflare API Shield labels a saved endpoint with no traffic for 32 days cf-risk-zombie. Here, and in Graphwake, the word means a gap in the record: an endpoint in the spec with no consumer team. An orphan in this sense may be called all day by a team that never said so.
Why it matters
When an endpoint with no recorded consumers changes, the producer has no one to warn. Either nobody calls it, or someone does and will find out in production.
Retirement stalls, too. Without a consumer list nobody can say whether the endpoint is safe to remove, so it stays forever. (We wrote separately about how to deprecate an endpoint safely.)
Ownership decays quietly. Teams split, merge and rename. An owner field that points at a team that no longer exists is worse than an empty one, because it looks filled.
And there's a security angle. The OWASP API Security Top 10 lists improper inventory management (API9:2023): hosts without a clear purpose, no retirement plan, missing or outdated documentation. An endpoint nobody owns is part of that problem.
How to find them from your specs
Your OpenAPI specs list every endpoint that exists. Start there, not from traffic, so the list is complete on one side. With a JSON spec and jq, list each operation as a method and a path:
jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | select(test("^(get|put|post|delete|patch|head|options|trace)$")) | "\(ascii_upcase) \($p)"' openapi.json | sort > endpoints.txt Then compare it with whatever records consumers today: a sheet, a wiki page, catalog entries. In this example it's a two-column file, METHOD /path,team. The lines that only appear in the spec are your orphans:
cut -d, -f1 consumers.csv | sort -u | comm -23 endpoints.txt - For a made-up orders-api with three of its four endpoints on record, the output is:
GET /orders/{id}/invoice Do the same with an owners list to find endpoints without an owner. If owners are set per service, an endpoint without its own owner inherits the service's. Only an endpoint whose service has no owner either is truly unowned.
What to do with each orphan
Finding one means you have something to check. Look at the endpoint's traffic, then pick one of three answers.
| What you see | What it means | What to do |
|---|---|---|
| Calls from a caller you can name | A consumer that never put itself on record | Ask that team to add itself (finding which teams use an endpoint covers the search) |
| No calls over a full business cycle | Probably unused | Confirm with the owner, then retire it with notice |
| A new endpoint, not released to callers yet | Nobody is meant to call it yet | Leave it, and look again after the first consumer ships |
Don't delete an orphan just because it's an orphan. Only remove it once the traffic shows nobody calls it over a full business cycle and the owner agrees.
For an endpoint with no owner, someone just has to decide: whoever owns the service, or the team that changes the code most often, takes it. Write it down even if it's a guess you'll correct later.
A weekly routine
- Get the list on Monday. Orphan endpoints, endpoints without an owner and services without an owner, sent to the people who can assign owners. Short lists get read, so cap each one.
- Triage the new lines. Each new orphan gets one of the three answers above. Each unowned service or endpoint gets an owner, or a name and a date for the decision.
- Ask, don't chase. Send one message per likely consumer team, naming the endpoint and the evidence. A team that says "not ours" has given you an answer too.
- Watch the count, not the list. The number should fall and then stay low. A sudden rise usually means a new service came in with no consumers mapped yet.
How Graphwake reports orphans
In Graphwake an orphan endpoint is a live endpoint that no consumer team subscribes to. Graphwake reads every endpoint from your OpenAPI specs and the subscriptions teams make, so the comparison above runs on its own and the weekly list arrives without anyone building it.
Example: the Monday email to admins.
Every Monday from 08:00 UTC, admins get one email listing orphan endpoints, endpoints without an owner and services without an owner, up to 50 lines each. A week with nothing to report sends nothing, and admins can turn it off.
Ownership is optional and inherits. A service may have an owner team, and an endpoint may have its own. An endpoint without one inherits the service's owner, so only real gaps show up.
The service graph flags each orphan endpoint next to its owner, and the overview counts them. A breaking change on an orphan counts toward the impact score as a blind spot.
When an orphan is new or changes in a breaking way, Discovery suggests teams from rules such as subscriptions to neighbouring endpoints and shared schemas. Someone confirms before a team subscribes.
If all you need to know is whether an endpoint is called at all, your gateway analytics or access logs answer that.
Originally published on graphwake.com.
How many endpoints in your specs have a consumer on record somewhere? Has anyone on your team ever run the numbers?
About Graphwake. We build Graphwake, a dependency map for your APIs. It watches your OpenAPI specs, knows which teams consume each endpoint, and tells only those teams in Slack, Microsoft Teams or email when a change is about to break them. Start a 7-day free trial at graphwake.com

