Skip to main content

API Dependency Graph

Visualize and manage dependencies between mock simulations, track impact of changes, and identify cascading failures. The dependency graph helps teams understand their mock ecosystem and make safer changes.

Prerequisites​

  • Multiple mock simulations in your workspace
  • Understanding of simulation relationships
  • Optional: Knowledge of microservices architecture

Understanding the Dependency Graph​

The dependency graph maps how simulations depend on each other:

Components:

  • Nodes - Simulations (shown as circles/boxes)
  • Edges - Dependencies (arrows showing relationships)
  • Manual Dependencies - Explicitly defined by users
  • Auto-Discovered Dependencies - Found in response bodies

Dependency Types:

TypeDirectionMeaning
InternalSimulation A → Simulation BA calls B's API
ExternalSimulation A → External URLA calls real API
BidirectionalA ↔ BBoth call each other

Viewing the Dependency Graph​

Simulation-Level View​

See dependencies for one simulation:

  1. Open simulation
  2. Click Dependencies tab
  3. View all dependencies (manual and auto-discovered)
  4. See source and target simulation names
  5. Check dependency confidence scores

Workspace Graph​

See all simulations and dependencies:

  1. Open workspace
  2. Click Dependency Graph or Architecture
  3. View visual graph:
    • All simulations as nodes
    • Dependencies as edges
    • Color coding for dependency types
    • Force-directed layout for clarity

Company Graph​

Enterprise view across entire company:

  1. Go to analytics/admin area
  2. Click Company Dependency Graph
  3. See all simulations from all workspaces
  4. Identify cross-workspace dependencies
  5. Spot potential conflicts

Manual Dependencies​

Explicitly define relationships between instances.

Add Manual Dependency​

  1. Open source simulation
  2. Click Add Dependency
  3. Select target simulation or enter external URL:
{
  "target_instance_id": "payment-service-id",
  "type": "internal",
  "reason": "Calls payment validation endpoint"
}

Or external:

{
  "target_url": "https://stripe.com/v1/charges",
  "type": "external",
  "reason": "Real Stripe API for payment processing"
}
  1. Click Create
  2. Dependency appears in graph

Remove Dependency​

Delete a dependency:

  1. Open dependencies list
  2. Find dependency
  3. Click Remove or delete icon
  4. Confirm removal

Removed dependencies are immediately removed from graph.

Auto-Discovery Scanning​

Automatically find dependencies from response bodies.

Scan Simulation​

Discover dependencies by analyzing responses:

  1. Open simulation
  2. Click Dependencies > Scan
  3. System analyzes all response bodies for URLs
  4. Found URLs are matched against other instances
  5. Auto-discovered dependencies are added

Scan Results​

View what was discovered:

Scanned 12 responses in simulation "payment-service"

Discovered URLs:
✓ https://internal.surestage.io/user-service/v1/users -> user-service (MATCHED)
✓ https://internal.surestage.io/inventory-service/v1/stock -> inventory-service (MATCHED)
✓ https://external-api.example.com/validate -> (EXTERNAL)
✓ https://stripe.com/v1/charges -> (EXTERNAL)

Added 2 internal, 2 external auto-discovered dependencies
Previous auto-discovered: Removed 3, Updated 0

Review Auto-Discovered​

  1. Go to dependencies
  2. Filter by "Auto-Discovered"
  3. Review found dependencies
  4. Remove false positives if needed

Auto-discovered dependencies are marked with a star or icon.

Impact Analysis​

Understand who depends on your simulation.

View Impact​

See which simulations would be affected if this simulation changes:

  1. Open simulation
  2. Click Impact or Dependents
  3. View reverse dependency tree

Impact Report:

Simulation: user-service

If this simulation changes, these simulations are affected:

Direct Dependents (1 level):
├─ payment-service (HIGH impact - 3 calls to /users)
├─ notification-service (LOW impact - 1 call)
└─ inventory-service (MEDIUM impact - 2 calls)

Transitive Dependents (2 levels):
├─ checkout-service (via payment-service)
├─ billing-service (via payment-service)
└─ reports-service (via inventory-service)

Depth 3+: 2 additional simulations

Summary:
- Direct: 3 simulations affected
- Transitive: 5 simulations affected
- Total: 8 simulations in dependency chain

Impact Depth​

Check cascading failures:

  1. Depth 1 - Direct dependents only
  2. Depth 2 - Their dependents
  3. Depth 3 - And so on

Greater depth = greater blast radius of changes.

Dependency Health​

Monitor health of dependencies.

Health Status​

Check if dependencies are healthy:

  1. Open simulation
  2. Click Dependencies > Health
  3. See health report:
Dependency Health Check

dependency: user-service
├─ Status: HEALTHY (✓)
├─ Simulation exists: Yes
├─ Simulation active: Yes
├─ Target routes exist: Yes
│  ├─ /api/users (200 OK)
│  └─ /api/users/{id} (200 OK)
└─ Last checked: 2 minutes ago

dependency: payment-service (external)
├─ Status: DEGRADED (!)
├─ Connectivity: WARN - Response times elevated (avg 850ms)
├─ Availability: INFO - Last failure 2 hours ago
└─ Last checked: 5 minutes ago

dependency: old-inventory (removed)
├─ Status: BROKEN (✗)
├─ Simulation exists: No
├─ Action needed: Remove or update dependency
└─ Last checked: 10 minutes ago

Health Statuses:

StatusMeaningAction
HealthyWorking normallyNone needed
DegradedSlow/intermittentMonitor
BrokenNot accessibleFix or remove

Common Workflows​

Understanding Service Architecture​

  1. Open Company Graph
  2. Review overall structure
  3. Identify bottlenecks (highly connected simulations)
  4. Spot single points of failure
  5. Plan improvements

Planning Safe Changes​

  1. Make change to simulation A
  2. View Impact analysis
  3. See all affected simulations
  4. Test all downstream simulations
  5. Roll out change safely

Onboarding New Service​

  1. Create new simulation
  2. Add manual dependencies to integrations
  3. Trigger auto-discovery to find more
  4. Visualize in dependency graph
  5. Verify all connections healthy

Migration Planning​

  1. View dependencies for old service
  2. Identify all callers
  3. Update each to point to new service
  4. Verify health checks pass
  5. Remove old service

Incident Investigation​

  1. Service goes down
  2. View impact analysis for that service
  3. See all affected services
  4. Prioritize fixes by impact
  5. Coordinate rollback if needed

Dependency Graph Best Practices​

Keep Dependencies Accurate​

  • Scan regularly for auto-discovery
  • Remove dependencies no longer used
  • Document reasons for dependencies
  • Keep external URLs current

Minimize Blast Radius​

  • Reduce depth of dependency chains
  • Identify bottlenecks (highly connected simulations)
  • Consider breaking into independent services
  • Add circuit breakers/fallbacks

Monitor Dependency Health​

  • Regular health checks
  • Alert on degraded status
  • Remove broken dependencies
  • Test dependent simulations after changes

Change Management​

  1. Before changing: Check impact analysis
  2. During change: Monitor dependents
  3. After change: Run health checks
  4. Document changes for team

Visualizing Dependencies​

Graph Visualization​

The visual graph shows:

  • Node size - Number of dependent simulations
  • Edge thickness - Strength of dependency
  • Color coding - Internal vs. external
  • Force layout - Related simulations cluster

Legends:

Node Colors:
● Green - Production/stable
● Yellow - Development/staging
● Red - Deprecated/broken

Edge Types:
→ Solid - Direct dependency
⇢ Dashed - Transitive (2+ hops)
⇢ Dotted - External dependency

Filtering Graph​

Focus on specific parts:

  1. Click Filter in graph view

  2. Show/hide:

    • Internal dependencies only
    • External dependencies only
    • Specific simulations
    • Depth N levels

  3. Export graph as:

    • PNG/SVG image
    • JSON for analysis
    • DOT format for Graphviz

Troubleshooting​

Dependency Not Found​

  • Verify target simulation exists
  • Check simulation name spelling
  • Target might be in different workspace
  • Use auto-discovery to find URLs in responses

Auto-Discovery Not Finding Dependencies​

  • Ensure response bodies contain URLs
  • URL format must match simulation hostname/path
  • Check simulation must exist in workspace
  • Re-run scan if simulations were recently added

Health Check Failing​

  • Verify target simulation is running/active
  • Check network connectivity
  • Confirm target routes still exist
  • Review error messages for details

Impact Analysis Shows Too Much​

  • Check for circular dependencies (A→B→A)
  • Verify dependencies are actually used
  • Remove false positive dependencies
  • Review depth limit setting

API Reference​

Dependency Management​

MethodPathDescription
GET/instances/:id/dependenciesList dependencies
POST/instances/:id/dependenciesAdd dependency
DELETE/instances/:id/dependencies/:depIdRemove dependency
POST/instances/:id/dependencies/scanScan for dependencies

Analysis Endpoints​

MethodPathDescription
GET/instances/:id/impactGet impact analysis
GET/instances/:id/dependencies/healthCheck health status

Graph Endpoints​

MethodPathDescription
GET/dependency-graphCompany-wide graph
GET/workspaces/:wsId/dependency-graphWorkspace graph

Next Steps​