What this example shows
A directed graph of HTTP / SDK dependencies between services, with edge labels showing the actual endpoint or SDK call rather than abstract “depends on” arrows. The “Web App” and “Mobile App” hit the gateway, the gateway fans out to auth / users / orders / catalog APIs, internal services call each other (orders → billing, orders → users, catalog → search), and external SDK integrations (Stripe, SendGrid) sit at the edge of the graph.
When to use it
When your platform has more than ~10 services and “who calls whom” is no longer something a single engineer holds in their head. The diagram is invaluable for: scoping deprecation work (who’d be affected if we sunset Catalog?), auditing third-party data exposure (which services hand data to which vendors?), incident scoping (when Billing is down, what else fails?), and onboarding (here’s the call graph; here’s the entry points).
What the agent does
The agent scans the OpenAPI specs in your repo (and / or grep for SDK imports - import Stripe from "stripe"), builds the directed call graph, then applies typed operations to the persisted scene. New endpoints become new edge labels; new services become nodes; deprecated endpoints disappear from the graph. Each change is a new revision, so the diagram is never rebuilt from scratch.
Edge labels show the actual endpoint where space allows (“POST /v1/login”, “GET /users/:id”) rather than abstract direction. For high-cardinality calls (e.g. dozens of REST endpoints between gateway and a single service), the agent collapses them to a representative (“REST”) to keep the diagram readable.
What the output includes
- A directed call graph with stable element IDs across runs (the same service keeps the same
elementIdevery time). - Edge labels showing endpoint paths or SDK names - readers learn the integration shape from the diagram alone.
- External systems (Stripe, SendGrid, etc.) visually distinct via the
externalSystemnode type. - Auto-layout via
layoutStrategy: { direction: "LR" }- the agent never hand-positions; the engine figures it out. - Synthesized background bands grouping nodes by
nodeTypeviaextensions.autoGroup: "byNodeType"at the top of the document - the engine emits subtle “Services” and “External Systems” regions so the reader scans the call graph as a layered architecture instead of a flat blob of floating shapes. - A revision history showing how the API surface evolved (which endpoints existed when).
Rendered diagram
Drawn by Zindex from the scene below with POST /v1/diagrams/preview.
Open it in the Playground to swap themes (clean / dark / blueprint / sketch),
or add format: "png" to the same request for a PNG.
Scene JSON
Raw
The DSP scene the diagram above is drawn from. Open it in the
Playground, or send it as scene to
POST /v1/diagrams/preview to draw it yourself.
{
"schemaVersion": "0.1",
"diagramFamily": "architecture",
"scene": {
"id": "api-dependency-map",
"title": "API Dependency Map",
"brief": "Which services call which: the web and mobile apps, the API gateway, the internal APIs and the third parties they use.\nBuilt from each service's OpenAPI spec and SDK imports; change it with edits from those, keeping element IDs, never by starting over. Edges run from caller to callee, labeled with the call (method and path), REST or the SDK's name. Third parties are external systems. Keep the left-to-right layout: clients, gateway, then services.",
"units": "px",
"canvas": {
"width": 1200,
"height": 600
}
},
"extensions": {
"autoGroup": "byNodeType"
},
"layoutStrategy": {
"direction": "LR",
"nodeSpacing": 60,
"rankSpacing": 130
},
"elements": [
{
"id": "web",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Web App",
"icon": "lucide:monitor"
},
{
"id": "mobile",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Mobile App",
"icon": "lucide:smartphone"
},
{
"id": "gateway",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "API Gateway",
"icon": "lucide:network"
},
{
"id": "auth_api",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Auth API",
"icon": "lucide:lock"
},
{
"id": "users_api",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Users API",
"icon": "lucide:users"
},
{
"id": "orders_api",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Orders API",
"icon": "lucide:package"
},
{
"id": "catalog_api",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Catalog API",
"icon": "lucide:boxes"
},
{
"id": "billing_api",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Billing API",
"icon": "lucide:credit-card"
},
{
"id": "search_api",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Search API",
"icon": "lucide:search"
},
{
"id": "stripe",
"kind": "node",
"nodeType": "externalSystem",
"shape": "roundedRect",
"label": "Stripe",
"icon": "lucide:external-link"
},
{
"id": "sendgrid",
"kind": "node",
"nodeType": "externalSystem",
"shape": "roundedRect",
"label": "SendGrid",
"icon": "lucide:mail"
},
{
"id": "e_web_gw",
"kind": "edge",
"from": {
"elementId": "web"
},
"to": {
"elementId": "gateway"
},
"label": "REST",
"router": "orthogonal"
},
{
"id": "e_mob_gw",
"kind": "edge",
"from": {
"elementId": "mobile"
},
"to": {
"elementId": "gateway"
},
"label": "REST",
"router": "orthogonal"
},
{
"id": "e_gw_auth",
"kind": "edge",
"from": {
"elementId": "gateway"
},
"to": {
"elementId": "auth_api"
},
"label": "POST /v1/login",
"router": "orthogonal"
},
{
"id": "e_gw_users",
"kind": "edge",
"from": {
"elementId": "gateway"
},
"to": {
"elementId": "users_api"
},
"label": "GET /v1/users",
"router": "orthogonal"
},
{
"id": "e_gw_orders",
"kind": "edge",
"from": {
"elementId": "gateway"
},
"to": {
"elementId": "orders_api"
},
"label": "REST",
"router": "orthogonal"
},
{
"id": "e_gw_catalog",
"kind": "edge",
"from": {
"elementId": "gateway"
},
"to": {
"elementId": "catalog_api"
},
"label": "REST",
"router": "orthogonal"
},
{
"id": "e_orders_billing",
"kind": "edge",
"from": {
"elementId": "orders_api"
},
"to": {
"elementId": "billing_api"
},
"label": "POST /charge",
"router": "orthogonal"
},
{
"id": "e_orders_users",
"kind": "edge",
"from": {
"elementId": "orders_api"
},
"to": {
"elementId": "users_api"
},
"label": "GET /users/:id",
"router": "orthogonal"
},
{
"id": "e_catalog_search",
"kind": "edge",
"from": {
"elementId": "catalog_api"
},
"to": {
"elementId": "search_api"
},
"label": "POST /index",
"router": "orthogonal"
},
{
"id": "e_billing_stripe",
"kind": "edge",
"from": {
"elementId": "billing_api"
},
"to": {
"elementId": "stripe"
},
"label": "Stripe SDK",
"router": "orthogonal"
},
{
"id": "e_orders_sendgrid",
"kind": "edge",
"from": {
"elementId": "orders_api"
},
"to": {
"elementId": "sendgrid"
},
"label": "SendGrid SDK",
"router": "orthogonal"
}
]
} Agent workflow
Build a diagram of which services expose, consume, and depend on which APIs by parsing OpenAPI specs and SDK imports across the repository, then change the saved Zindex diagram with typed operations when the API topology changes.
Inputs
- Glob of OpenAPI spec files in the monorepo (e.g. services/*/openapi.yaml)
- Glob of source files that import generated SDKs (used to derive consumer→provider edges)
- The diagram's Zindex key or ID
- A Zindex API key, or an MCP client signed in to Zindex
Outputs
- A new revision of the diagram with one node per service and one edge per cross-service call
- Rendered SVG showing the current API topology
- A compare listing newly added consumers / providers since the last run
- 01
Create or read the diagram
On the first run, save the parsed map with
diagram_create, a hierarchical LR layoutStrategy, akeysuch asapi-dependency-mapand abriefwhose first line says what the map shows; Zindex mints the ID; the key is how later runs find it, and the brief's first line is what a search shows. Repeating the same create returns the existing diagram, so a retry never makes a copy. On later runs, read it by key withdiagram_getinstead. - 02
Parse OpenAPI specs
Walk every services/*/openapi.yaml in the monorepo. Each spec becomes a service node; emit operationIds + paths so they can later become edge labels (e.g. 'POST /v1/login'). Do not parse free-text README links - the spec is the source of truth.
- 03
Derive consumer→provider edges
Scan source files for imports of generated SDKs (e.g.
import { usersClient } from '@acme/sdk-users'). Each import is evidence that the importing service consumes the imported API. Map the SDK package name back to the spec → an edge from consumer to provider, labeled with the most-frequently-called operationId. - 04
Diff the parsed topology against the diagram
Read the diagram's outline: its first line gives the current revision, and each line after it gives a service or an edge with its label. New services become createNode ops; removed services become deleteElement ops; changed labels become updateEdge ops. Always reuse stable element ids (the service name) so a renamed label stays on the same edge.
- 05
Save the changes as one edit
Send the diff as one
diagram_editwithbaseRevisionset to the revision you read and amessagethat says what changed. The edit is all or nothing: if an operation has errors, it returnsVALIDATION_FAILEDand saves nothing. Reuse stable element ids -users_api,orders_api,e_orders_users- so renames update the existing element rather than create a duplicate. - 06
Fix what the warnings report
The edit's
warningslist what checking and drawing the new revision noticed, each with acode, theelementwhen there is one, and a one-linefix. The edit above returnsLABEL_DUPLICATION_DETECTEDbecausee_gw_ordersande_gw_catalogboth say 'REST'. That is expected where many calls are collapsed to 'REST'; anywhere else, give each edge its own label in a follow-up edit. - 07
Render the new revision
Get SVG and PNG links to the new revision; they work without a key for 7 days. The hierarchical LR layout naturally separates clients (left), gateway (center), and provider APIs (right); cloud-icon services render icon-only and read cleanly inside the layout.
- 08
List what changed since the last run
Compare the revision you started from with the new one: the result lists the element IDs added, changed and removed. New or removed services and calls are the cross-service dependencies worth telling the team about.
- 09
Publish the rendered SVG to the docs site
Download the SVG from its link and upload it to the docs site (or commit it to the repo's docs/ directory). When the compare lists added or removed services, post a Slack message to the platform channel so the team is aware of the new dependency.
MCP recipe
For agents using Model Context Protocol. The tool sequence below matches the workflow steps; copy the prompt as a system message.
Tool sequence
- 01
diagram_createCreate or read the diagram - 02
diagram_getDiff the parsed topology against the diagram - 03
diagram_editSave the changes as one edit - 04
diagram_renderRender the new revision - 05
diagram_historyList what changed since the last run
Unique tools used: diagram_create, diagram_get, diagram_edit, diagram_render, diagram_history.
Copyable agent prompt
Drop this verbatim into a system prompt for an MCP-connected agent.
The Zindex MCP server at https://api.zindex.ai/mcp exposes
the tools the prompt references (connect a client),
and so does the npm package @zindexai/mcp, which forwards
to it.
You maintain the API dependency map that the platform team keeps in Zindex: one diagram of which services expose, consume and depend on which APIs across the organization's microservices. When asked to update it, you parse the OpenAPI specs and SDK imports in the monorepo and change the diagram with typed edits, each with a message saying what changed. Every revision is kept, so anyone can open the map as it was on any date.
The diagram's Zindex ID is `${SCENE_ID}`; it already exists. Each update computes the smallest valid set of typed operations that move the diagram from its current revision to one that matches what you parsed. If nothing changed, send nothing; an edit that changes nothing makes no revision anyway.
Steps for each update:
1. Walk every `services/*/openapi.yaml` in the monorepo. Each spec corresponds to one service node - use the spec's `info.title` (or the directory name) as the stable element id. Capture the operationIds and paths so they can become edge labels.
2. Walk every source file in the monorepo and look for imports of generated SDK packages (`@acme/sdk-users`, `@acme/sdk-orders`, …). Each import is evidence that the importing service consumes the imported API. Build a `(consumer_service_id, provider_service_id, operationId)` tuple for the most-frequently-called operation between each pair.
3. Call `diagram_get({ id: "${SCENE_ID}" })`. The outline's first line gives the current revision, and each line after it gives a service (ID, type, label) or an edge (`id: from -> to "label"`). Diff what you parsed against it: new services → `createNode`, removed services → `deleteElement`, new edges → `createEdge`, removed edges → `deleteElement`, changed edge labels → `updateEdge`.
4. Call `diagram_edit({ id: "${SCENE_ID}", baseRevision, message, ops })` with one batch, `baseRevision` set to the revision you read. The edit is all or nothing. Reuse stable element ids - `users_api`, `orders_api`, `e_orders_billing` - so a renamed service or relabeled edge stays on the same element rather than producing a delete+create. Pass a meaningful `message` like "add billing-api spec; new e_orders_billing edge from POST /charge". If the call returns `REVISION_CONFLICT`, the map changed after you read it: the error lists what changed, so re-plan against the new revision.
5. An edit with errors returns `VALIDATION_FAILED` and saves nothing. A saved edit returns `warnings`: what checking and drawing the new revision noticed, each with a `code`, the `element` when there is one, and a one-line `fix`. `LABEL_DUPLICATION_DETECTED` means edges that start or end at one service share a label, which is expected where you collapsed many calls to 'REST' and worth fixing anywhere else. `EDGE_COLUMN_NOT_FOUND` should not appear here; if it does, an edge is using ER-family `column` anchors by mistake and needs `from/to.elementId` only. Fix the rest with a follow-up edit.
6. Call `diagram_render({ id: "${SCENE_ID}" })`. It returns SVG and PNG links to the new revision, valid for 7 days. Download the SVG and publish it to the docs site (or commit it to `docs/architecture/api-topology.svg`). The image prints its address, `zindex.ai/d/<id>@<revision>`, and date, so the published image is traceable back to its revision.
7. Call `diagram_history({ id: "${SCENE_ID}", compare: { from: PREV_REVISION } })`; it lists the element IDs added, changed and removed since then. If it contains added or removed services (new providers or consumers), post a short Slack message to the platform channel summarizing the change so the team is aware of the new cross-service dependency.
Hard rules: never hand-edit the rendered SVG; always edit the diagram with `diagram_edit` and render again. Never recreate the diagram from scratch; always patch with stable ids - the topology is a long-lived, evolving graph, and stable ids are what make revision history meaningful. Treat the OpenAPI specs as the source of truth; if a spec contradicts a free-text comment elsewhere, follow the spec.
HTTP API recipe
For agents/devs not using MCP. Send
Authorization: Bearer $ZINDEX_API_KEY on every call
except POST /v1/diagrams/validate and
POST /v1/diagrams/preview, which need no key. In the
paths, ${SCENE_ID} is the diagram's ID, or the
key you gave it in diagram_create. Full
reference: REST API, OpenAPI spec.
- 01
POST/v1/diagramsOn the first run, save the parsed map with
diagram_create, a hierarchical LR layoutStrategy, akeysuch asapi-dependency-mapand abriefwhose first line says what the map shows; Zindex mints the ID; the key is how later runs find it, and the brief's first line is what a search shows. Repeating the same create returns the existing diagram, so a retry never makes a copy. On later runs, read it by key withdiagram_getinstead.Example response
{ "id": "dgm_bsEyV7SiWCoa", "key": "api-dependency-map", "revision": 1, "hash": "sha256:8f15604a40c52b5fdaa36cf2992d6e34c1b96827acb4a424ca1093d60496bd7a", "chain": "sha256:ae53b52766b548119dd31da2fae87501de567d41cf3cc3d9371b72df7611f733", "warnings": [ { "code": "LABEL_DUPLICATION_DETECTED", "fix": "Edges e_gw_orders, e_gw_catalog share the label 'REST': merge them or give each its own label." } ], "created": true } - 02
GET/v1/diagrams/${SCENE_ID}Read the diagram's outline: its first line gives the current revision, and each line after it gives a service or an edge with its label. New services become createNode ops; removed services become deleteElement ops; changed labels become updateEdge ops. Always reuse stable element ids (the service name) so a renamed label stays on the same edge.
Example response
{ "id": "dgm_bsEyV7SiWCoa", "revision": 1, "text": "dgm_bsEyV7SiWCoa \"API Dependency Map\" r1 2026-10-31T18:21Z sha256:8f15604a40c5\nkey: api-dependency-map\nbrief: Which services call which: the web and mobile apps, the API gateway, the internal APIs and the third parties they use.\n Built from each service's OpenAPI spec and SDK imports; change it with edits from those, keeping element IDs, never by starting over. Edges run from caller to callee, labeled with the call (method and path), REST or the SDK's name. Third parties are external systems. Keep the left-to-right layout: clients, gateway, then services.\nrecent: r1 curl/8.7.1 \"First map from the OpenAPI specs\"\noutline: 10 nodes, 9 edges\n web service \"Web App\"\n mobile service \"Mobile App\"\n gateway service \"API Gateway\"\n auth_api service \"Auth API\"\n users_api service \"Users API\"\n orders_api service \"Orders API\"\n catalog_api service \"Catalog API\"\n search_api service \"Search API\"\n stripe externalSystem \"Stripe\"\n sendgrid externalSystem \"SendGrid\"\n e_web_gw: web -> gateway \"REST\"\n e_mob_gw: mobile -> gateway \"REST\"\n e_gw_auth: gateway -> auth_api \"POST /v1/login\"\n e_gw_users: gateway -> users_api \"GET /v1/users\"\n e_gw_orders: gateway -> orders_api \"REST\"\n e_gw_catalog: gateway -> catalog_api \"REST\"\n e_orders_users: orders_api -> users_api \"GET /users/:id\"\n e_catalog_search: catalog_api -> search_api \"POST /index\"\n e_orders_sendgrid: orders_api -> sendgrid \"SendGrid SDK\"" } - 03
POST/v1/diagrams/${SCENE_ID}/revisionsSend the diff as one
diagram_editwithbaseRevisionset to the revision you read and amessagethat says what changed. The edit is all or nothing: if an operation has errors, it returnsVALIDATION_FAILEDand saves nothing. Reuse stable element ids -users_api,orders_api,e_orders_users- so renames update the existing element rather than create a duplicate.Example request body
{ "baseRevision": 1, "message": "add billing-api spec; new e_orders_billing edge from POST /charge", "ops": [ { "op": "createNode", "id": "billing_api", "nodeType": "service", "shape": "roundedRect", "label": "Billing API", "icon": "lucide:credit-card" }, { "op": "createEdge", "id": "e_orders_billing", "from": { "elementId": "orders_api" }, "to": { "elementId": "billing_api" }, "label": "POST /charge", "router": "orthogonal" }, { "op": "createEdge", "id": "e_billing_stripe", "from": { "elementId": "billing_api" }, "to": { "elementId": "stripe" }, "label": "Stripe SDK", "router": "orthogonal" } ] }Example response
{ "id": "dgm_bsEyV7SiWCoa", "revision": 2, "hash": "sha256:5ebe42a5b03af394e3a95b0613231d95c2292a1d90aa99ed2aa89cf886e5849f", "chain": "sha256:dba03555fc519a023f18cf3f768ad8506d0350ee56094bcec913c10f8e150054", "warnings": [ { "code": "LABEL_DUPLICATION_DETECTED", "fix": "Edges e_gw_orders, e_gw_catalog share the label 'REST': merge them or give each its own label." } ], "changed": { "added": [ "billing_api", "e_orders_billing", "e_billing_stripe" ], "updated": [], "removed": [] } } - 04
GET/v1/diagrams/${SCENE_ID}/renderGet SVG and PNG links to the new revision; they work without a key for 7 days. The hierarchical LR layout naturally separates clients (left), gateway (center), and provider APIs (right); cloud-icon services render icon-only and read cleanly inside the layout.
Example response
{ "id": "dgm_bsEyV7SiWCoa", "title": "API Dependency Map", "revision": 2, "latest": 2, "savedAt": "2026-10-31T18:21:45.100Z", "hash": "sha256:5ebe42a5b03af394e3a95b0613231d95c2292a1d90aa99ed2aa89cf886e5849f", "chain": "sha256:dba03555fc519a023f18cf3f768ad8506d0350ee56094bcec913c10f8e150054", "engine": "8.11.0+build.2597", "svg": "https://api.zindex.ai/v1/images/dgm_bsEyV7SiWCoa@2.svg?e=1794075705&s=...", "png": "https://api.zindex.ai/v1/images/dgm_bsEyV7SiWCoa@2.png?e=1794075705&s=...", "expires": "2026-11-07T18:21:45.000Z", "width": 1119, "height": 903 } - 05
GET/v1/diagrams/${SCENE_ID}/compare?from=${PREV_REVISION}Compare the revision you started from with the new one: the result lists the element IDs added, changed and removed. New or removed services and calls are the cross-service dependencies worth telling the team about.
Example response
{ "id": "dgm_bsEyV7SiWCoa", "from": 1, "to": 2, "added": [ "billing_api", "e_orders_billing", "e_billing_stripe" ], "changed": [], "removed": [], "scene": [], "authors": [ { "by": null, "client": "curl/8.7.1" } ] }
Operations
Raw The typed operations that build this diagram from empty. Save an
empty diagram with diagram_create, then send the
envelope's baseRevision, message and
ops to diagram_edit, or
POST /v1/diagrams/{id}/revisions. Each op
carries a stable id so subsequent runs can update the
same elements instead of regenerating.
{
"schemaVersion": "0.1",
"sceneId": "api-dependency-map",
"baseRevision": 1,
"message": "Initial API dependency map: clients, gateway, internal APIs, external systems",
"ops": [
{
"op": "createNode",
"id": "web",
"nodeType": "service",
"shape": "roundedRect",
"label": "Web App",
"icon": "lucide:monitor"
},
{
"op": "createNode",
"id": "mobile",
"nodeType": "service",
"shape": "roundedRect",
"label": "Mobile App",
"icon": "lucide:smartphone"
},
{
"op": "createNode",
"id": "gateway",
"nodeType": "service",
"shape": "roundedRect",
"label": "API Gateway",
"icon": "lucide:network"
},
{
"op": "createNode",
"id": "auth_api",
"nodeType": "service",
"shape": "roundedRect",
"label": "Auth API",
"icon": "lucide:lock"
},
{
"op": "createNode",
"id": "users_api",
"nodeType": "service",
"shape": "roundedRect",
"label": "Users API",
"icon": "lucide:users"
},
{
"op": "createNode",
"id": "orders_api",
"nodeType": "service",
"shape": "roundedRect",
"label": "Orders API",
"icon": "lucide:package"
},
{
"op": "createNode",
"id": "catalog_api",
"nodeType": "service",
"shape": "roundedRect",
"label": "Catalog API",
"icon": "lucide:boxes"
},
{
"op": "createNode",
"id": "billing_api",
"nodeType": "service",
"shape": "roundedRect",
"label": "Billing API",
"icon": "lucide:credit-card"
},
{
"op": "createNode",
"id": "search_api",
"nodeType": "service",
"shape": "roundedRect",
"label": "Search API",
"icon": "lucide:search"
},
{
"op": "createNode",
"id": "stripe",
"nodeType": "externalSystem",
"shape": "roundedRect",
"label": "Stripe",
"icon": "lucide:external-link"
},
{
"op": "createNode",
"id": "sendgrid",
"nodeType": "externalSystem",
"shape": "roundedRect",
"label": "SendGrid",
"icon": "lucide:mail"
},
{
"op": "createEdge",
"id": "e_web_gw",
"from": {
"elementId": "web"
},
"to": {
"elementId": "gateway"
},
"label": "REST",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_mob_gw",
"from": {
"elementId": "mobile"
},
"to": {
"elementId": "gateway"
},
"label": "REST",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_gw_auth",
"from": {
"elementId": "gateway"
},
"to": {
"elementId": "auth_api"
},
"label": "POST /v1/login",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_gw_users",
"from": {
"elementId": "gateway"
},
"to": {
"elementId": "users_api"
},
"label": "GET /v1/users",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_gw_orders",
"from": {
"elementId": "gateway"
},
"to": {
"elementId": "orders_api"
},
"label": "REST",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_gw_catalog",
"from": {
"elementId": "gateway"
},
"to": {
"elementId": "catalog_api"
},
"label": "REST",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_orders_billing",
"from": {
"elementId": "orders_api"
},
"to": {
"elementId": "billing_api"
},
"label": "POST /charge",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_orders_users",
"from": {
"elementId": "orders_api"
},
"to": {
"elementId": "users_api"
},
"label": "GET /users/:id",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_catalog_search",
"from": {
"elementId": "catalog_api"
},
"to": {
"elementId": "search_api"
},
"label": "POST /index",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_billing_stripe",
"from": {
"elementId": "billing_api"
},
"to": {
"elementId": "stripe"
},
"label": "Stripe SDK",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_orders_sendgrid",
"from": {
"elementId": "orders_api"
},
"to": {
"elementId": "sendgrid"
},
"label": "SendGrid SDK",
"router": "orthogonal"
}
]
} Validation
Valid
Captured response from POST /v1/diagrams/validate, the
check diagram_validate runs. It checks the scene and
draws it. Every code it can return is in the validation rules.
- 0 errors
- 1 warning
-
warningLABEL_DUPLICATION_DETECTEDEdges e_gw_orders, e_gw_catalog share the label 'REST': merge them or give each its own label.
Each entry has a code, the element it
concerns when there is one, and a one-line fix.
diagram_create and diagram_edit save
nothing when there are errors and return
VALIDATION_FAILED; warnings don't block a save. Both
return the same warnings for the revision they save, so an agent
reads them from the write itself.
Revision diff
Raw
What changed between two revisions of the diagram, as
diagram_history returns it with compare.
Every revision is kept, so any two can be compared, by revision
number or by date.
Scenario
The map's first save. Revision 1 is the empty diagram and revision 2 applies the operations in ops.json, so every service and call is added and nothing is changed or removed. Each later update compares the same way and names only what it changed, such as a new API and the calls to it, which is quicker to review than re-reading the OpenAPI specs.
- Revision 1 → 2
- +22 added
- -0 removed
- ~0 changed
+ Added
webmobilegatewayauth_apiusers_apiorders_apicatalog_apibilling_apisearch_apistripesendgride_web_gwe_mob_gwe_gw_authe_gw_userse_gw_orderse_gw_cataloge_orders_billinge_orders_userse_catalog_searche_billing_stripee_orders_sendgrid
Raw compare response
{
"id": "dgm_jivBZnikoXjM",
"from": 1,
"to": 2,
"added": [
"web",
"mobile",
"gateway",
"auth_api",
"users_api",
"orders_api",
"catalog_api",
"billing_api",
"search_api",
"stripe",
"sendgrid",
"e_web_gw",
"e_mob_gw",
"e_gw_auth",
"e_gw_users",
"e_gw_orders",
"e_gw_catalog",
"e_orders_billing",
"e_orders_users",
"e_catalog_search",
"e_billing_stripe",
"e_orders_sendgrid"
],
"changed": [],
"removed": [],
"scene": [],
"scenario": "The map's first save. Revision 1 is the empty diagram and revision 2 applies the operations in ops.json, so every service and call is added and nothing is changed or removed. Each later update compares the same way and names only what it changed, such as a new API and the calls to it, which is quicker to review than re-reading the OpenAPI specs."
}
To compare two versions of your own diagram, call
diagram_history with compare: { from, to },
or GET /v1/diagrams/{id}/compare with
from and to, giving revision numbers or
dates. With an API key,
GET /v1/images/{id}@{to}.svg?from={from}
draws the later version with what changed colored.
Agent resources
Machine-readable versions of this example. Agents should fetch these rather than scrape the rendered HTML.
-
api-dependency-map.scene.jsonCanonical DSP scene Open -
api-dependency-map.ops.jsonTyped-operation envelope that builds the scene Open -
api-dependency-map.workflow.jsonStructured agent workflow (goal, inputs, outputs, steps) Open -
api-dependency-map.diff.jsonSamplediagram_historycompare response Open -
api-dependency-map.svgRendered diagram Open -
api-dependency-map.mdAgent-readable markdown summary Open -
/examples/index.jsonManifest of all examples (cross-linked) Open