Before a team changes an endpoint, someone has to answer a plain question: who calls this? In most companies the answer lives in people's heads, in an old wiki page, or in a Slack thread that starts after something broke.
We build Graphwake, which tells the teams that consume an API when a change in its OpenAPI spec is about to break them, so it needs that answer for every endpoint. What you're really asking about is a relationship between teams and endpoints, so we stored it as one, in a graph. It turns out to need very little: three kinds of node, three kinds of edge, and queries that are one or two hops long.
Three nodes, three edges
| Node | What it is | Where it comes from |
|---|---|---|
| Service | One API with its own OpenAPI spec, such as orders-api. | Set up in Graphwake with its spec, from a published URL or a CI step. |
| Endpoint | One method and path of a service, such as GET /orders/{id}. | Read from the spec. A removed endpoint stays on record for its history. |
| Team | A group of people with one place for alerts: a Slack channel, a Microsoft Teams channel or an email address. | Created in Graphwake by the people who run it. |
| Edge | From → to | Kept by | Rule |
|---|---|---|---|
| exposes | Service → Endpoint | The spec | Every endpoint belongs to exactly one service. |
| owns | Team → Service, or Team → Endpoint | An admin | Optional, and a single team. An endpoint with its own owner overrides its service's owner; otherwise it inherits it. |
| subscribes to | Team → Endpoint | The consumer team | Per whole endpoint. A team subscribes to each endpoint it calls. |
The consumer graph. An endpoint with no subscriber is an orphan.
The graph in Graphwake
Here's the same model drawn for one example service, as Graphwake shows it. orders-api is owned by payments-team. Its endpoint GET /orders/{id} has two subscribed consumer teams, checkout and mobile-app, and one team Discovery suggests, storefront. GET /orders/{id}/invoice has no subscriber at all: an orphan, shown as a blind spot. The rest of this post uses that example.
Example: the orders-api service graph in Graphwake.
Graphwake draws each service this way, as three columns: the owner, the endpoints, and the teams that consume them, with a table view of the same data. Click an endpoint and you get its owner, its consumers, its Discovery suggestions and its history.
The graph is also the routing table. When a spec change breaks GET /orders/{id}, the alert goes to checkout and mobile-app, each in the Slack channel, Microsoft Teams channel or email address it picked, plus anyone who follows the endpoint by email. storefront isn't subscribed, so it gets no alert (at most one clearly labelled Discovery note, covered below), and no company-wide channel hears about it either.
A sketch of the model
The graph is small and shallow, so four relational tables hold it comfortably. This is a generic sketch of the shape, not Graphwake's schema:
-- Example: a minimal relational sketch of the model. Not Graphwake's schema. CREATE TABLE teams ( id uuid PRIMARY KEY, name text NOT NULL UNIQUE ); CREATE TABLE services ( id uuid PRIMARY KEY, name text NOT NULL UNIQUE, owner_team_id uuid REFERENCES teams (id) -- optional: owns ); CREATE TABLE endpoints ( id uuid PRIMARY KEY, service_id uuid NOT NULL REFERENCES services (id), -- exposes method text NOT NULL, path text NOT NULL, owner_team_id uuid REFERENCES teams (id), -- optional override removed_at timestamptz, -- kept for history UNIQUE (service_id, method, path) ); CREATE TABLE subscriptions ( -- subscribes to team_id uuid NOT NULL REFERENCES teams (id), endpoint_id uuid NOT NULL REFERENCES endpoints (id), created_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY (team_id, endpoint_id) ); A few choices in there are worth spelling out.
Ownership is a nullable column rather than a table. One team answers for a service, and an endpoint may name a different one. It may stay empty, because an unowned endpoint you can see is more useful than a wrong name.
A subscription is a row with a composite key, so a team subscribes to an endpoint once. There's no field column, because a subscription covers the whole endpoint.
Endpoints aren't deleted. When an endpoint disappears from the spec it's marked removed. The live graph hides it, and the change history still points at it.
Edges have history too. Graphwake records each subscribe and unsubscribe, each ownership change, and each published change with the teams it reached. So it can later show that checkout heard about a change because it subscribed to GET /orders/{id} three months earlier.
Why the consumers keep the list
The producer team looks like the natural owner of a consumer list, but it's in a poor position to keep one. The producer sees requests arrive, but not which team's code sent them or what that code relies on.
Each consumer team knows exactly which endpoints it calls, and it learns this at a precise moment: when it writes the integration. Recording the edge at that moment takes a minute. Reconstructing it later from the producer's side takes a search across every repository, and that search still misses some callers.
So a subscription is a consumer team saying "we call this". The side that has the knowledge declares the edge, and nobody has to infer it.
The list stays current because we route every breaking change along it. A team that missed an alert finds out why and subscribes. A team that keeps getting alerts it doesn't need removes the edge.
A team that isn't subscribed isn't told, and the producer can see that this was a decision rather than an oversight. In a broadcast channel there's no way to tell a team that isn't affected from one that missed the post. And an endpoint with no subscriber shows up as an orphan, with a count next to it, so the gap is on screen rather than in someone's head.
Traffic logs and code search still help you find callers you don't know about yet (API consumer tracking compares those methods). They tell you which client called recently, or which repository contains a URL. A subscription tells you which team wants to hear when the contract changes, and that's what you need to know when a change breaks it.
Three questions the graph answers
Who does this change affect?
Start from the endpoints a change set touches and follow the subscription edges back to teams. One hop.
-- Example: which teams does a change to these endpoints reach? SELECT DISTINCT t.name FROM subscriptions s JOIN teams t ON t.id = s.team_id WHERE s.endpoint_id = ANY ($1); -- the endpoints with a breaking change In the example, a breaking change to GET /orders/{id} reaches checkout and mobile-app, and no other team. A breaking change to GET /orders/{id}/invoice reaches nobody, and that's the result to worry about. Graphwake counts it as a blind spot in the change's impact score, so the gap shows while the change is still a pull request.
What does my team depend on?
Start from a team, follow its subscription edges to endpoints, then each endpoint's owner edge (or its service's) to the team to ask. Two hops.
-- Example: what does one team depend on, and whom does it ask about each endpoint? SELECT sv.name AS service, e.method, e.path, ot.name AS owner -- the endpoint's owner, else the service's FROM subscriptions s JOIN endpoints e ON e.id = s.endpoint_id AND e.removed_at IS NULL JOIN services sv ON sv.id = e.service_id LEFT JOIN teams ot ON ot.id = COALESCE(e.owner_team_id, sv.owner_team_id) WHERE s.team_id = $1 ORDER BY sv.name, e.path, e.method; For checkout, that's GET /orders/{id} in orders-api, owned by payments-team, plus whatever else checkout calls. A team wants this list in front of it when it plans an upgrade or runs an incident review. Your AI assistant can read the same list through Graphwake MCP.
Which endpoints have no owner or no consumer?
Look for endpoints with a missing edge: no subscription, or no owner on either the endpoint or its service.
-- Example: live endpoints with no consumer (orphans) or no owner SELECT sv.name AS service, e.method, e.path, NOT EXISTS (SELECT 1 FROM subscriptions s WHERE s.endpoint_id = e.id) AS orphan, COALESCE(e.owner_team_id, sv.owner_team_id) IS NULL AS unowned FROM endpoints e JOIN services sv ON sv.id = e.service_id WHERE e.removed_at IS NULL AND (NOT EXISTS (SELECT 1 FROM subscriptions s WHERE s.endpoint_id = e.id) OR COALESCE(e.owner_team_id, sv.owner_team_id) IS NULL); An orphan is either unused or unmapped, and you can't tell which from the graph alone. An unowned endpoint has nobody to ask. Graphwake flags orphans on the service graph and, when the weekly report is turned on, emails admins a weekly list of orphan endpoints, endpoints without an owner and services without an owner.
Do you need a graph database for any of this? Usually not. The useful questions are one or two hops, and a few relational tables with the right keys answer them. A graph database starts to pay off when you need long, variable-length paths, which a team-to-endpoint map rarely does.
Filling the gaps: Discovery
A declared graph is only as complete as its declarations. New endpoints and forgotten subscriptions need a nudge.
Discovery is rule-based. After every spec arrives, it looks at each new endpoint and each endpoint with a breaking change, and asks which teams that aren't subscribed may be affected. It uses only data the graph already holds, and it shows every signal it found as the reason for the suggestion.
| Signal | What it reads | In the example |
|---|---|---|
| Subscriptions nearby | The team subscribes to another endpoint of the same service under the same path prefix. | storefront subscribes to GET /orders, next to GET /orders/{id}. |
| Shared schema | The team subscribes to an endpoint whose request body or success response uses the same named schema. | storefront also subscribes to POST /orders, which returns the same Order schema as GET /orders/{id}. |
| Ownership | The team owns the service or the endpoint. | payments-team, for a new endpoint in orders-api (on its own, too weak to be listed). |
| Maybe moved | The change set removed an endpoint and added another that may replace it; the old endpoint's subscribers are suggested for the new one. | If GET /orders/{id} were replaced by GET /v2/orders/{id}, checkout and mobile-app would be suggested for the new path. |
| Past decisions | The team said "Not us" to another endpoint with the same schema. This lowers the score. | A team that already declined an Order endpoint is less likely to be suggested for the next one. |
Each signal adds a fixed weight and a past "Not us" subtracts one, with the total kept between 0 and 100. There's no language model involved. Suggestions under 40 are counted but not listed, so weak guesses stay out of people's way.
A person always decides. The suggested team (or an admin) chooses Confirm, which subscribes the team, or Not us. A decision is final for that team and endpoint, and a subscribed team is never suggested. When a released change breaks an endpoint and a suggestion for it scores 60 or more, the suggested team gets one "This may affect you" note with Confirm and Not us links. A workspace can turn this off.
One weak signal isn't enough. storefront is listed because two signals agree: a nearby subscription and a shared schema. If the orphan GET /orders/{id}/invoice changed in a breaking way, the path rule would point at checkout and mobile-app, because both subscribe to GET /orders/{id} just above it. On its own that rule scores under 40, so those suggestions are counted but not shown, and the orphan stays a visible blind spot until a team subscribes.
What the model leaves out
Each of these omissions is deliberate, and each one keeps the graph small enough for people to maintain.
There are no field-level subscriptions. A team subscribes to a whole endpoint, so a removed field reaches every subscriber of that endpoint, including a team that never read it. The cost is an occasional alert a team marks as handled. In return, the list stays small enough for a person to keep accurate.
There's no traffic or code analysis. Graphwake reads only the OpenAPI spec. It doesn't read source code or request logs, so an edge exists because a team declared it or confirmed a suggestion.
Consumers are teams, not services. A breaking change is a conversation between people, so the graph records who to talk to, not which process opens the connection. A team has members and a channel; a service doesn't read Slack.
Each node has one owner. When two teams share ownership, questions tend to go unanswered. The model allows one team per service and one override per endpoint.
Follows aren't edges. Anyone can follow an endpoint and get its alerts by email, but a follow isn't a subscription: it never appears in the graph, the consumer list, the impact score or Discovery.
Originally published on graphwake.com.
Where does "who calls this endpoint" live at your company today? A catalog, a spreadsheet, gateway logs, or someone's memory?
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



