Mastering Mermaid Sequence Diagrams for API Design

When designing APIs and microservices, flowcharts are not always enough. You often need to show time, ordering, ownership, retries, and which system is waiting for a response. Sequence diagrams are ideal for that job because they show interactions from top to bottom as the scenario unfolds.

This tutorial focuses on practical Mermaid sequence diagrams for API documentation. Copy each example into the Mermaid Preview editor, render it, then adapt the participants and message labels to match your own services.

Participants and Actors

Sequence diagrams rely on entities communicating with each other. Mermaid lets you define them explicitly. An actor usually represents a human user or external role, while a participant represents a system, service, browser, queue, database, or third-party API.

sequenceDiagram
  actor User
  participant API
  participant DB

You can also give a participant a short ID and a longer display name. This keeps the source readable while still showing a clear label in the diagram.

sequenceDiagram
  actor User
  participant Web as Web App
  participant Auth as Authentication API
  participant IdP as Identity Provider

Messages and Responses

You define communication using arrows. A solid line ->> is commonly used for a request or command, while a dotted line -->> is commonly used for a response. Keep labels specific: POST /login is more useful than send request.

sequenceDiagram
  User->>API: GET /users/123
  API-->>User: 200 OK (User Data)

Activations (Lifelines)

To show that a service is actively processing a request, use activate and deactivate, or the shorthand + and -. Activations are useful when a request crosses multiple services and you want to make waiting time visible.

sequenceDiagram
  User->>+API: Process Payment
  API->>+Bank: Charge Card
  Bank-->>-API: Success
  API-->>-User: Receipt

Notes, Alternatives, and Loops

You can add explanatory notes over participants using the Note keyword. For branches, Mermaid supports alt and else. For repeated work such as polling or retries, use loop.

sequenceDiagram
  actor User
  participant App
  participant API

  User->>App: Submit form
  App->>API: POST /orders
  alt valid request
    API-->>App: 201 Created
    App-->>User: Show confirmation
  else validation error
    API-->>App: 400 Bad Request
    App-->>User: Show field errors
  end

Complete Login Flow Example

A useful sequence diagram usually tells one story. This login example shows the user, browser, application API, identity provider, and session store. It includes the happy path and the invalid credentials path without trying to document every possible exception.

sequenceDiagram
  autonumber
  actor User
  participant Browser
  participant API as App API
  participant IdP as Identity Provider
  participant Session as Session Store

  User->>Browser: Enter email and password
  Browser->>+API: POST /login
  API->>+IdP: Verify credentials

  alt credentials valid
    IdP-->>-API: User identity
    API->>+Session: Create session
    Session-->>-API: Session id
    API-->>Browser: 204 No Content + Set-Cookie
    Browser-->>User: Redirect to dashboard
  else credentials invalid
    IdP-->>API: Authentication failed
    API-->>-Browser: 401 Unauthorized
    Browser-->>User: Show login error
  end

Documenting Retries and Timeouts

Retries are hard to explain in prose because the same message may happen several times. A loop block makes this explicit and gives reviewers a place to discuss backoff, limits, and failure behavior.

sequenceDiagram
  participant Worker
  participant Payments
  participant Queue

  Worker->>Payments: Capture payment
  loop up to 3 attempts
    Payments-->>Worker: Timeout
    Worker->>Payments: Retry with backoff
  end
  Worker->>Queue: Publish payment_failed

Best Practices for API Sequence Diagrams

• Start with one scenario: login success, payment failure, retry exhaustion, or cache miss. Avoid documenting an entire platform in one diagram.
• Name real boundaries: show browser, API, queue, database, and third-party services as separate participants when ownership matters.
• Use HTTP methods and status codes: labels such as POST /orders and 201 Created are more useful than generic request text.
• Show important failures: add alt branches for expected errors that developers or support teams need to understand.
• Keep notes short: notes should clarify assumptions, not replace the diagram with paragraphs.

Common Mermaid Sequence Errors

• If an arrow renders incorrectly, check that you used ->> or -->> consistently.
• If a participant name contains spaces, define it with an alias such as participant API as Billing API.
• If activations look unbalanced, make sure every + request eventually has a matching - response.
• If the diagram is too wide, shorten participant labels and move details into message text or surrounding documentation.

Sequence diagrams are powerful because they expose timing and responsibility before a team writes or changes code. Try pasting these snippets into the Mermaid Preview editor, then export SVG for documentation or copy the source into Markdown.

Related Resources

• Copy Mermaid diagram examples
• Mermaid flowchart tutorial
• Embedding Mermaid diagrams in Markdown