On this page
What a team-level map holds
The unit is the endpoint, a method and a path, not the service. A service with forty endpoints may have one consumer for thirty-nine of them and six for the last one. A change to one endpoint matters only to the teams that call that one.
| Part | What it records | Why it is there |
|---|---|---|
| Service and endpoints | Every live endpoint, read from the service’s OpenAPI spec | The map follows the spec, so a new endpoint appears when the spec ships it |
| Owner | The team responsible for the service, or for one endpoint inside it | Someone to ask. Optional: a missing owner is shown, not guessed |
| Consumers | The teams that depend on each endpoint | The people to warn when the endpoint changes |
| Blind spots | Endpoints no team has said it uses | A change there reaches nobody, which is either fine or a gap |
| History | Who subscribed, who changed what, who was told | So the map can be trusted, and argued with |
Teams, not people and not services, are the right level. People move between teams and services get renamed, but a team has a channel and someone who reads it. When a spec changes, the question is “which teams do I tell?”, and a map of service names still needs someone to translate each one into a team.
Four ways to draw the map
Every map is a set of edges. What matters is what an edge means and who put it there. Tool facts below are from each vendor’s own docs, checked on 2026-11-09.
| Source | An edge means | Good at | Misses |
|---|---|---|---|
| Gateway analytics (Apigee, Gravitee, Kong, AWS API Gateway) | A known client called this API through the gateway | Real call volumes per client; external customers | Calls that bypass the gateway, and callers without their own key |
| Traces and service mesh (OpenTelemetry, Istio with Kiali) | Service A called service B in the time window you look at | Live topology, latency and errors between services | Uninstrumented services, unsampled calls, callers that did not run in the window |
| Catalog declarations (Backstage, Apigee API hub, Azure API Center) | Someone wrote down that this depends on that | A whole-system inventory with owners | Usually API-level, not endpoint-level; mostly kept by hand, so it drifts |
| Consumer subscriptions | A team said it depends on this endpoint | Whom to warn before a change merges | Callers that never subscribed, until someone finds them |
Gateway analytics
A gateway sees every call routed through it and attributes it to the key or application the caller sent, so the edge is “this key called this API”. To warn someone you still map each key to a team, and internal calls that skip the gateway are not in the data; API consumer tracking covers keys in Gravitee, Kong and AWS API Gateway in detail.
Traces and the service mesh
Tracing draws the map from calls as they happen. The OpenTelemetry Collector’s service graph connector (alpha) pairs client and server spans into edges and emits request and error metrics per edge; it needs every span of a trace to reach the same collector instance. A service with no instrumentation appears only as a “virtual node” guessed from the caller’s span. Kiali draws an Istio mesh from the request data in Prometheus, combined with the mesh configuration.
This is the most honest picture of what runs. It is also a picture of a time window: a monthly billing job, a client that ships next week, or a call that was not sampled is not on it. And its nodes are services, named by whoever set service.name.
Catalog declarations
A catalog mostly records relations someone wrote down. In Backstage, a Component lists providesApis and consumesApis in its catalog-info.yaml, and every Component and API needs an owner. The relations point at API entities, not at single endpoints. Apigee API hub models a dependency as a supplier and a consumer, each an API operation or an external API. A dependency is proposed when API hub identifies it on its own, and validated when an admin confirms it or someone creates it by hand. Azure API Center’s dependency tracker links a source and a target resource you pick in the portal, and does not delete a dependency when its resource is deleted.
A catalog is the right home for ownership of the whole system. Its weakness is upkeep: the producer team often writes the entry, but the consumer is the one who knows what it calls.
Consumer subscriptions
A subscription flips who keeps the list. Each consumer team marks the endpoints it calls, once, in the same place every team uses. The producer never maintains a list of consumers; it reads one. The edge is a statement of intent, so it covers the monthly job and the client that has not shipped yet, and it is attached to a team with a channel. Its weakness is the team that never subscribed. Those gaps have to be visible, not silent.
Using a declared map and a traffic map together
- Before a change merges: the declared map says which teams to warn, while the change is still a pull request.
- Before an endpoint is removed: traffic confirms that the teams on the map really stopped calling it, and shows any caller the map missed. The endpoint retirement checklist puts both in order.
- After an incident: compare the two. A caller in the traces that is not on the map is a team to ask to subscribe.
How to build a team-level map
Start from the specs
Collect the OpenAPI spec of each service: a published URL or the file in the repository. The specs give you every endpoint, so the map starts complete on one side.
Name owners where it is clear
Give each service an owner team, and override it on an endpoint only where another team really owns it. Leave the rest empty: an unowned endpoint you can see is better than a wrong name.
Have consumer teams subscribe
Ask each team to mark the endpoints it calls. Start with the services that change most. Searching code and logs helps a team find what it calls; see how to find which teams use an endpoint.
Review the blind spots
Endpoints with no consumers are either unused or unmapped. Look at them on a schedule, and ask the likely teams before the next change there. See orphaned API endpoints for a weekly routine.
Use the map when you change an API
Before a breaking change merges, tell the subscribed teams. The map stays current because it is used: a team that finds out it was missing subscribes then.
What Graphwake keeps
Graphwake builds this map from your OpenAPI specs and team subscriptions alone: nothing to install in your traffic path, no code access. The service graph shows each service’s owners, its live endpoints and the teams that consume each one, and an endpoint with no consumer team is flagged as an orphan.
Subscriptions per endpoint
Each consumer team subscribes to the endpoints it calls. A breaking change alerts only those teams, in Slack, Microsoft Teams or email.
Optional ownership
A service may have an owner team, and an endpoint may have its own. A weekly report lists orphan endpoints and what has no owner.
Discovery for the gaps
When an endpoint is added or breaking-changed and nobody is mapped to it, Discovery suggests likely teams from rules, each with a reason and a score. A team becomes a subscriber only when someone confirms it.
Blind spots count
A breaking change on an endpoint nobody subscribes to adds to the impact score, so the gap shows up before the merge.
Discovery’s rules use what Graphwake already holds: subscriptions to neighbouring endpoints, shared request and response schemas, ownership, an endpoint that may replace a removed one, and earlier “Not us” answers. A team suggested at 60% or more gets a one-time “This may affect you” note when a breaking change goes live. Anyone can also follow an endpoint for email alerts; a personal follow is not a consumer and never appears on the map.
With Graphwake MCP on Pro and Enterprise, the same map answers your AI assistant: who owns an endpoint, which teams consume it, and what a local spec change would reach. See ask your AI assistant who breaks.
When a traffic or catalog map alone is enough
- You need proof that nobody calls an endpoint before you delete it. Gateway logs or traces over a long enough window are that evidence.
- Your consumers are external customers with API keys. Gateway analytics already know each caller and its volume.
- You are debugging latency or failures between services. A trace-based service graph shows the live calls, errors and timings.
Where to go next
- To compare gateway keys, access logs, tracing and subscriptions in detail, read API consumer tracking.
- To route alerts with the map, read API breaking change alerts.
- To see how blind spots and affected teams turn into a number, read the impact score rules.
- For why an assistant cannot work this out from your repository alone, read does your AI assistant know who uses your API?.
Questions
What is an API dependency map?
A record of which teams or services call which API endpoints, and who owns each one. It can be drawn from traffic (gateway logs, traces) or from declarations (a catalog, or consumer teams subscribing to endpoints).
How is it different from a service map in my tracing tool?
A tracing service map shows which services called each other in a time window, with latency and errors. A team-level dependency map shows which teams depend on each endpoint, including callers that did not run in that window, and whom to warn about a change.
Does Backstage already give me this?
Partly. Backstage records which components provide and consume which APIs, with an owner for each. The relations are at API level, not per endpoint, and are written by hand in catalog-info.yaml. It is a good place for ownership; it does not route change alerts.
Can a declared map be wrong?
Yes: a team can call an endpoint without subscribing. Make the gaps visible (endpoints with no consumers), check traffic before you remove an endpoint, and ask teams to subscribe when you find a caller. Graphwake’s Discovery suggests likely teams, which someone then confirms or dismisses.
Does Graphwake read traffic or code to build the map?
No. It reads your OpenAPI specs and the subscriptions teams make. Discovery suggestions come from rules over that same data, not from traffic or code.
Pick an endpoint. See who it reaches. 7-day free trial. Cancel before day 7 and you pay nothing.
Start free trialSources and last verified
- documentation.gravitee.io/apim/secure-and-expose-apis/subscriptions
- documentation.gravitee.io/apim/secure-and-expose-apis/plans/keyless
- developer.konghq.com/gateway/entities/consumer/
- docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html
- github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/connector/servicegraphconnector/README.md
- kiali.io/docs/architecture/architecture/
- kiali.io/docs/features/topology/
- backstage.io/docs/features/software-catalog/descriptor-format/
- docs.cloud.google.com/apigee/docs/apihub/api-supply-chain
- docs.cloud.google.com/apigee/docs/reference/apis/apihub/rest/v1/projects.locations.dependencies
- learn.microsoft.com/en-us/azure/api-center/track-resource-dependencies
Sources checked on 2026-11-09.