API Dependency Mapping: See What Breaks Before You Change It

API dependency mapping is the practice of recording which APIs call, feed values to, or wait on other APIs, so you can see what a change will touch before you make it. A good map answers three questions fast: what does this API depend on, what depends on it, and how do we know. This guide shows how to build one from real evidence, how to read a blast radius, and how to put the map to work in testing.

Ask a team which APIs depend on the payments service and you will usually get three answers from three people. Each answer is partly right. That is the problem a dependency map solves: it replaces memory and meeting-room diagrams with something you can check.

What an API dependency map is

An API dependency map is a graph. Each node is an API operation, such as POST /orders or GET /payments/{id}. Each edge is a relationship between two operations, with a direction and a reason.

It differs from the architecture diagram on the wiki in three ways:

It works at the endpoint level. A service-level box that says "Orders talks to Payments" does not tell you which operations are involved.
It comes from evidence. Every edge has a source you can point to.
It is kept current. It is rebuilt from sources, not redrawn by hand once a quarter.

The four kinds of link

Not every connection means the same thing. Mixing them up produces maps that look busy but answer nothing. Keep these four apart.

Kind of link	What it means	Example	Matters for
Calls	One API invokes another while handling a request	`POST /orders` calls `POST /payments/charge`	Blast radius, mocks, failure testing
Uses a value from (data flow)	A value returned by one API is an input to another	`id` from `POST /customers` is used in `GET /customers/{id}`	Test data, ordering, chained tests
Runs after (sequence)	A step must happen before another, with no value passed	Create an account, then activate it	Test order, workflow design
Looks like one resource	Two paths probably act on the same resource	`/users` and `/users/{id}`	Navigation only; never a dependency

The last row is a trap. Two paths that share a resource name are related, but a change to one does not necessarily break the other, so it should never count toward a blast radius.

Why teams need a dependency map

Change review. Before approving a change, you can list who and what it touches, instead of finding out in production.
Test ordering. Tests that create data must run before tests that read it. The map shows the order and the values passed along.
Mock planning. To test one API alone, you mock the APIs it calls. The map gives you that list. Our guide to API mocking for parallel development explains how those mocks are used.
Incident triage. When an API fails, the map shows which failures downstream are probably symptoms rather than separate bugs.
Integration test design. The map shows where service dependencies need tests, and where an end-to-end journey crosses several of them.

Where the evidence comes from

The most important idea in dependency mapping is that evidence has different strengths. A link you watched happen in traffic is stronger than one you inferred from a naming pattern. Record the source of every link and keep the sources apart.

Evidence	How you get it	Strength	Watch out for
Defined in a workflow or test	A test chain or workflow that passes a value from one call to the next	Strong	Only covers flows someone wrote
Seen happening	Distributed traces, gateway upstream routes, captured traffic, HAR files	Strong	Only covers the capture window; service-level traces may not name the endpoint
Stated by a person	A service catalogue entry or an owner who says "this tool calls these APIs"	Medium	Nothing has checked it
Suggested by a model, then confirmed	AI proposes links from names, a person accepts or dismisses	Medium	Only as good as the confirmation
Guessed from paths or names	`/orders/{id}/items` probably relates to `/orders/{id}`	Weak	Easy to over-trust

Some dependencies cannot be seen by tooling at all. An MCP tool that calls three REST APIs is a good example: the protocol does not say which ones, so a person has to state it. That is fine, as long as the map labels it "stated by a person".

If your services already emit traces, start there. Our guides to distributed tracing and OpenTelemetry for microservices show how to get that data.

Ready to shift left with your API testing?

Try our no-code API test automation platform free. Generate tests from OpenAPI, run in CI/CD, and scale quality.

Start Trial Book Demo

How to build a dependency map

Step 1: Start with one critical journey

Do not map the whole estate first. Pick one business flow, such as "place an order", and list every API it touches. A map of ten APIs that people trust is worth more than a map of 400 that nobody believes.

Step 2: Collect declared links

Pull links from what already exists: workflow definitions, chained test cases, callbacks in your specs, and service catalogue entries. These are cheap, and they say what the team intended.

Step 3: Add observed links

Compare intent with reality. Pull upstream routes from your gateway, derive calls from traces, or capture a session and read the calls it made. Observed links reveal the dependencies nobody wrote down, such as a legacy endpoint your new service still calls.

Step 4: Add the human-stated links

Ask owners about the gaps: events, scheduled jobs, MCP tools, and anything that sits outside the traced path. Record them as "stated by a person", with a name and a date.

Step 5: Label every edge with its evidence and age

An edge seen last week and an edge seen eight months ago are not the same. Expire observed links that have not been seen for a while, so the map does not keep its dead wiring forever.

Step 6: Review the guesses

If you use name-based suggestions, put them in a separate "to review" list. Accept the ones that match reality, dismiss the rest. A guess should never be promoted silently.

Reading a blast radius: a worked example

Take a small e-commerce flow with five APIs:

POST /checkout calls POST /orders.
POST /orders calls POST /inventory/reserve and POST /payments/charge.
POST /payments/charge calls POST /notifications/receipt.
GET /orders/{id} uses the order id returned by POST /orders.

Suppose the inventory team plans to change the response of POST /inventory/reserve.

Hop	Affected API	Why	Evidence
0	`POST /inventory/reserve`	The changed API	n/a
1	`POST /orders`	Calls the changed API	Seen in traces
2	`POST /checkout`	Calls an API that calls the changed one	Seen in traces
2	`GET /orders/{id}`	Uses a value from `POST /orders`	Defined in a test chain
not included	`POST /notifications/receipt`	Sits on a separate branch (payments)	n/a

Two details matter here. First, the blast radius follows calls and values, not run order. Second, limit the number of hops. Beyond three or four, nearly everything connects to everything, and the answer stops being useful. A sensible rule is to follow values and calls out to four hops and report "runs after" links only one hop away.

The practical result: the inventory team now knows to run tests for POST /orders, POST /checkout and GET /orders/{id}, and to tell the owners of those three APIs. It also knows the receipt service can be left alone.

Using the map in testing

Order your tests. Anything that produces a value runs before anything that consumes it. Put setup first and cleanup last.
Choose what to run for a change. Run the tests for the changed API and its one- and two-hop neighbours first, then widen if something fails. Regression testing is far cheaper when you know which tests matter.
Decide what to mock. To test POST /orders alone, mock inventory and payments. The map lists exactly what to stand in for.
Design end-to-end journeys. An end-to-end test across microservices should follow a real path on the map, not an imagined one.
Find contract gaps. A call between two teams with no contract test is a candidate for one.

Common mistakes

Mapping services instead of endpoints. "Orders depends on Payments" is not enough to choose tests.
Drawing it once. A map that is not rebuilt goes stale within a release or two.
Showing guesses as facts. One wrong edge makes people distrust the whole map.
Ignoring environments. A link seen only in staging does not prove the same wiring in production. Record the environment, and do not treat "unknown" as "all".
Counting similarity as dependency. Two paths about the same resource are not a call.
Forgetting asynchronous links. Events and queues create dependencies that request traces may not show. Add them by hand and label them.

How Shift-Left API handles dependencies

Everything above works with any tool, including a whiteboard and a spreadsheet. This section describes what Shift-Left API does, so you can compare.

Each API in a project has its own Dependencies tab, on every plan. It shows which APIs come before and after that API, which use its values, and how each link is known. A fuller dependency view sits inside Discovery, and that view needs the Discovery add-on (every trial includes it).

Free Visual blueprint + guide

Microservices Testing Strategy Blueprint

A visual testing strategy for microservices architectures. Covers testing layers, contract testing, service mesh validation, and tool selection.

Two separate ideas, shown separately. The map keeps what a link means apart from how we know it:

Meaning: Runs after, Uses a value from, Calls, and Looks like one resource.
Evidence: Set in a workflow, Seen happening, A person said so, Suggested by AI and confirmed by a person, and Guessed from the paths.

A link known in several ways keeps the strongest evidence and lists the rest. Guesses are hidden by default in the functional and combined views, and a checkbox ("Show the N guesses from the paths") reveals them. A "Looks like one resource" link is never treated as a dependency and is never counted in the blast radius.

Three views of the same graph. You can switch between End-to-end workflows, Functional dependencies and Both without any card moving. Each workflow gets its own colour, and "Follow" numbers a workflow's steps. Hovering shows a detail card, clicking pins it, and a full-screen mode makes a large map readable.

Blast radius. Impact follows values and calls out to four hops. A "runs after" link is reported one hop out only.

Where observed links come from. A HAR file, a live capture, a gateway route's upstream, and OpenTelemetry or Datadog traces. Service-level links are tied to endpoints only through operations you have accepted into the project, and the screen says when the endpoints involved are unknown. Observed links expire 90 days after they were last seen. An environment filter keeps a link seen in one environment from posing as "all environments".

People and AI can add links. For an MCP tool, a person states which APIs it calls, and the map shows "A person said so". AI can suggest links from names, but a suggestion waits for you to accept or dismiss it.

From the map to mocks. The mock server's "Mock the dependencies" action reads the project's dependency graph and creates draft, switched-off mocks for the APIs the chosen API calls or needs. An API that already has a mock gets no second one, and nothing answers until a person publishes it. See contract-checked API mocks for what to do next.

What it does not do. To set expectations honestly:

Workflow steps that call a WebSocket or JSON-RPC method carry no endpoint id, so they create no links.
Observed links need a capture, HAR file, gateway or trace to read. Without one, you see declared and stated links only.
Workflows do not automatically order or wire themselves from dependency evidence. Use the map to make those decisions yourself.
Tests do not automatically take their data from other tests.

Details are in the API dependencies guide. For multi-step flows built from the map, see integration test workflows. To try it on your own APIs, start a trial.

Dependency mapping checklist

✔ One critical journey is mapped first, not the whole estate
✔ Links are separated into calls, data flow, sequence and "looks like"
✔ Every link records its evidence and when it was last seen
✔ Observed links come from at least one source (traces, gateway or capture)
✔ Human-stated links name the person who stated them
✔ Guessed links are hidden by default and reviewed before use
✔ Blast radius follows calls and values to a fixed number of hops
✔ Environments are recorded on observed links
✔ Tests are ordered from the map: setup, use, cleanup
✔ Mocks are planned from the map for each API under test
✔ The map is rebuilt on a schedule, and stale links expire

Frequently asked questions about API dependency mapping

What is API dependency mapping?

API dependency mapping is the practice of recording which APIs call, feed values to, or must run before other APIs. The result is a graph you can query to find everything a change might affect.

How is an API dependency map different from an architecture diagram?

An architecture diagram is drawn once by hand and shows services. A dependency map is built from evidence, works at the endpoint level, and says how each link is known, so it can be checked and kept current.

What evidence should I use to build a dependency map?

Use declared evidence (workflows, specs and catalogue entries) and observed evidence (traces, gateway routes and captured traffic). Add owner knowledge for links that tooling cannot see, and treat anything inferred from names alone as a guess to confirm.

What is a blast radius in API testing?

The blast radius of a change is the set of APIs, tests and consumers that could be affected by it. You find it by following the links that carry values or calls away from the changed API, usually a few hops out.

Why should guessed links be kept separate from observed ones?

A link inferred from similar path names can be wrong. If it is shown the same way as a link seen in real traffic, people trust it and make decisions on a guess. Label the evidence and hide guesses by default.

Does Shift-Left API include dependency mapping on every plan?

The Dependencies tab on each API's page is available on every plan. The Dependencies view inside Discovery needs the Discovery add-on, which every trial includes.

Do Shift-Left API workflows understand dependencies automatically?

Not as a shipped capability. Workflows are built and ordered as before, and you can use the dependency map to decide how to order them. Do not rely on automatic ordering from dependency evidence.

Sources and further reading

OpenTelemetry: traces: the data most observed service links come from.
Martin Fowler: Microservices: why service boundaries and dependencies need active management.
Dependency graph (Wikipedia): the underlying idea and its terminology.