API Flow Visualizer: Document Your API Interactions
Sequence diagrams make complex API interactions understandable. This AI agent creates clear, professional diagrams showing request/response flows between services.
Create a detailed sequence diagram in Mermaid syntax that precisely models an API flow including request/response payloads, authentication, error handling, and asynchronous operations.
SEQUENCE DIAGRAM PROCESS:
1. Flow Analysis
- Identify all actors and services that participate in the flow (user, browser, API gateway, microservices, databases, external APIs)
- Determine the trigger event that initiates the flow
- Map the complete happy path from initiation to final response
- Identify all branching points: conditionals, error paths, retry logic
- Determine which operations are synchronous vs. asynchronous (fire-and-forget, event-driven, webhook callbacks)
2. Authentication and Authorization Modeling
- Show token acquisition or session establishment if it is part of this flow
- Show where tokens are validated and by which service
- Model token refresh flows if applicable
- Show authorization checks (role verification, permission checks) at the appropriate service boundary
- Indicate what happens when auth fails (401/403 responses)
3. Payload Design
- Include simplified but realistic request payloads at each service boundary (not every internal call)
- Show response payloads for both success and error cases
- Include HTTP status codes with each response arrow
- Show headers that are architecturally significant (Authorization, Content-Type, correlation IDs)
4. Error Path Modeling
- Model at least the 2-3 most important error scenarios as alt blocks
- Show error propagation: how an error in a downstream service surfaces to the caller
- Include timeout handling and retry logic if applicable
- Show compensation or rollback actions for failed multi-step operations
- Model circuit breaker behavior if relevant
5. Asynchronous Operations
- Distinguish sync calls (solid arrows) from async events (dashed arrows) using Mermaid syntax
- Show message queues or event buses as explicit participants
- Model callback or webhook flows with clear temporal ordering
- Show parallel operations using par blocks where applicable
- Indicate background jobs or scheduled tasks triggered by the flow
6. Diagram Quality
- Use activate/deactivate to show when each participant is processing
- Add notes for complex business logic that cannot be expressed as simple messages
- Use loop, alt, opt, and par blocks to model control flow clearly
- Keep message labels concise but precise (include HTTP method and path for API calls)
OUTPUT CONSTRAINTS:
- Produce valid Mermaid sequence diagram syntax that renders without errors
- Include at minimum: the happy path AND one error/alternate path
- Every message arrow must have a descriptive label
- Payloads should be simplified to key fields only (3-5 fields), not full schemas
- If information about error handling or auth is not provided, include reasonable defaults and mark with [ASSUMED]
- Add a written description of the flow below the diagram for context
FORMAT:
## Sequence Diagram: [Flow Name]
### Overview
[1-2 paragraph description of the flow, when it is triggered, and its outcome]
### Diagram
```mermaid
sequenceDiagram
[complete diagram code]
```
### Flow Description
[Step-by-step numbered walkthrough of the happy path]
### Error Scenarios
[Description of each error path shown in the diagram and how it is handled]
### Payloads Reference
[Table or JSON blocks showing the full request/response schemas for key interactions]
### Notes
[Assumptions, edge cases, or design decisions worth documenting]
---
MY INFO:
Flow Name (e.g., "User Authentication" or "Order Processing"): (required)
Actors/Services Involved: (required)
1.
2.
3.
4.
Step-by-Step Flow: (required)
1.
2.
3.
Authentication Mechanism (JWT, OAuth2, API key, session): (optional)
Known Error Scenarios to Include: (optional)
Asynchronous Operations (background jobs, events, webhooks): (optional)
Protocol Details (REST, gRPC, GraphQL, WebSocket): (optional)
What's Visualized
- Request/Response Flows: Complete data path
- Authentication: Token flow and validation
- Error Handling: Failure scenarios and fallbacks
- Async Operations: Background jobs and callbacks
Output Formats
- Mermaid syntax (GitHub-compatible)
- PlantUML format
- Visual diagram image
- Exportable for documentation
Use Cases
- API Documentation: Show how endpoints interact
- Onboarding: Help new developers understand flows
- Debugging: Trace request paths
- Design Reviews: Validate architecture decisions
Best Practices
- Keep diagrams focused on one flow
- Include error paths
- Show timing for async operations
- Label all data exchanges
Create diagrams that make complex systems understandable.