Visualize API request flows with Mermaid sequence diagrams

APIs live on request-response cycles: a client asks for something, a server responds. Documenting how that conversation flows—who calls whom, in what order, with what data—is critical. Mermaid sequence diagrams are perfect for this: they show the order of messages, who handles each step, and where failures can happen.

Why sequence diagrams for API flows?

A sequence diagram makes it obvious:

• Order of calls — this happens, then that happens (not a surprise when reading code).
• Who's involved — client, API gateway, auth service, database—all labeled and separated.
• Sync vs. async — solid arrows are requests; dashed arrows are responses or events.
• Error paths — show what happens when validation fails or a service is unavailable.
• Dependencies — see at a glance if one service blocks another or calls run in parallel.

Unlike a text description or prose documentation, a diagram is unambiguous. Everyone on the team sees the same flow.

Sequence diagram syntax for APIs

sequenceDiagram
    participant Client as Client / Browser
    participant API as API Gateway
    participant Auth as Auth Service
    participant DB as Database
    
    Client->>+API: GET /user/profile<br/>(with token)
    API->>+Auth: Validate token
    Auth-->>-API: Token OK, user_id
    API->>+DB: SELECT * FROM users<br/>WHERE id = ?
    DB-->>-API: User record
    API-->>-Client: 200 { user data }

Key syntax:

• ->> = sync call (solid arrow, request)
• -->> = response (dashed arrow)
• -x = fire-and-forget (no response expected)
• + after participant name = activation box opens (service is working)
• - before response = activation box closes

Real-world API flow examples

Example 1: OAuth 2 login flow

sequenceDiagram
    participant User as User / Browser
    participant App as Web App
    participant Auth as Auth Provider<br/>(Google, GitHub)
    
    User->>App: Click "Login with Google"
    App->>+Auth: GET /authorize?client_id=...<br/>&redirect_uri=...
    Note over Auth: User logs in on<br/>Google's site
    Auth-->>-App: Redirect with auth code
    App->>+Auth: POST /token (code, client_id,<br/>client_secret)
    Auth-->>-App: { access_token, refresh_token }
    App->>App: Store tokens in session
    App-->>User: Redirect to dashboard
    Note over User: User is logged in

Shows the multi-step OAuth dance: authorization, code exchange, and token storage.

Example 2: REST API with error handling

sequenceDiagram
    participant Client
    participant API as API Gateway
    participant Validate as Validation Service
    participant DB as Database
    
    Client->>+API: POST /orders<br/>{ items: [...], total: 99.99 }
    API->>+Validate: Validate order payload
    
    alt Payload invalid
        Validate-->>API: 400 Bad Request
        API-->>Client: 400 { error: "Missing items" }
    else Payload valid
        Validate-->>-API: OK
        API->>+DB: INSERT INTO orders ...
        DB-->>-API: Order ID 12345
        API-->>-Client: 201 { order_id: 12345 }
    end

Shows how the API branches on validation: success creates the order, failure returns an error.

Example 3: Async API with webhook callback

sequenceDiagram
    participant Client
    participant API as API Server
    participant Worker as Background Job<br/>Queue
    participant Webhook as Client's<br/>Webhook Endpoint
    
    Client->>+API: POST /generate-report
    Note over API: Request queued<br/>immediately
    API-->>-Client: 202 Accepted<br/>{ job_id: "job_xyz" }
    
    Note over Worker: Processing async
    Worker->>Worker: Generate 10MB report
    
    Worker->>+Webhook: POST /webhooks/report-ready<br/>{ job_id, report_url, status }
    Webhook-->>-Worker: 200 OK
    
    Note over Client: Client polls or<br/>listens for webhook
    Client->>API: GET /job/job_xyz
    API-->>Client: { status: "complete", url: "..." }

Perfect for documenting long-running operations: API returns immediately, then notifies the client when done.

Example 4: API with retry and timeout

sequenceDiagram
    participant Client
    participant API as API Gateway
    participant Service as Downstream<br/>Service
    
    Client->>+API: GET /data
    
    loop Retry up to 3 times
        API->>+Service: GET /endpoint
        
        alt Response received
            Service-->>-API: 200 { data }
            break Exit retry loop
        else Timeout (5s)
            Note over Service: No response
            API->>API: Wait 1s before retry
        end
    end
    
    alt Success
        API-->>-Client: 200 { data }
    else All retries failed
        API-->>-Client: 503 Service Unavailable
    end

Shows retry logic, timeouts, and the circuit-breaker pattern.

Example 5: Microservices chain with aggregation

sequenceDiagram
    participant Client
    participant Portal as Portal API
    participant User as User Service
    participant Order as Order Service
    participant Payment as Payment Service
    
    Client->>+Portal: GET /dashboard
    Portal->>+User: GET /user/profile
    User-->>-Portal: { name, email, tier }
    
    Portal->>+Order: GET /user/orders
    Order-->>-Portal: [ orders ]
    
    Portal->>+Payment: GET /user/subscriptions
    Payment-->>-Portal: [ active subscriptions ]
    
    Portal->>Portal: Merge responses
    Portal-->>-Client: 200 { user, orders,<br/>subscriptions }

Shows the portal aggregating data from multiple services, then returning it to the client.

Best practices for API sequence diagrams

1. Focus on one happy path per diagram. If your API has 10 different error cases, don't cram them all in. Show the success case clearly, then a separate diagram for error handling.

2. Label each message with the actual HTTP method or gRPC call. GET /user/profile is clearer than just Request.

3. Use Note blocks to explain business logic. "User logs in on Google's site" makes the diagram readable without source docs.

4. Show response codes and payloads. 200 { user data } or 400 Bad Request tells readers exactly what to expect.

5. Use alt (if-then-else) for decision points. Validation failure vs. success, authentication required vs. allowed, etc.

6. Keep activation boxes (+ / -) to show who's working when. Helps spot parallelism vs. blocking.

7. Use par for parallel calls (when applicable):

par
    Portal->>User: GET /user
and
    Portal->>Order: GET /orders
and
    Portal->>Payment: GET /subscriptions
end

Shows the three services are called concurrently, not in sequence.

Where to use API sequence diagrams

• API documentation — in your README or spec alongside cURL examples
• Architecture design docs — show how services talk during setup or deployment
• Onboarding — help new team members understand the request flow
• Bug reports — "The login flow fails here" with a diagram is clearer than prose
• Design reviews — propose a new API flow and discuss with teammates

Examples in your repo

Store API flow diagrams alongside your OpenAPI/Swagger specs:

api/
├── user-service.md
├── user-service-flow.md  (sequence diagrams)
├── openapi.yaml
└── examples/
    └── login-flow.md

Exporting and embedding

Paste any of the examples above into MermaidCreator's playground to view, edit, and export as PNG or SVG:

```mermaid
sequenceDiagram
    participant Client
    participant API
    Client->>+API: GET /data
    API-->>-Client: 200 OK
```

FAQ

Can I show a request timeout in a sequence diagram? Yes, use a loop with a break statement when the response arrives. See Example 4 above.

How do I show request headers or payload details? Use Note blocks: Note over Client: Include Authorization header.

Should I diagram every single error case? No. Document happy paths clearly; link to error-handling docs separately. One diagram per primary flow.

What's the difference between a sequence diagram and a flowchart with swimlanes? Sequence diagrams emphasize message order and timing (who calls whom, then what happens). Swimlanes emphasize service ownership (which service owns which steps). Use sequence for "how does the request flow?" and swimlanes for "who's responsible for what?"

Can I add authentication or API keys to the diagram? Yes, include them in the message label: POST /endpoint (Authorization: Bearer token).

How do I keep diagrams in sync with API changes? Treat them like code: include in PRs, review in API design meetings, and update when you ship breaking changes. Store in your repository, not external tools.

Ready to document your API flows? Create a sequence diagram in MermaidCreator's playground now.