OnUML LogoOnUML

Mermaid Sequence Diagram Examples for APIs and Databases

··7 min read
mermaidsequence-diagramexamplesapi-documentation

The most useful Mermaid sequence diagram examples are complete enough to expose a real contract: who starts the interaction, which service owns each decision, what is persisted, and how failure changes the response. The six templates below cover common API and database scenarios and can be pasted into the Mermaid Sequence Diagram Online Editor.

Each Mermaid sequence diagram examples template renders in Mermaid 11.17.2. Replace the participant names, endpoints, and business outcomes with the vocabulary of your system; do not copy timeout, retry, or consistency claims unless they match the implementation.

Mermaid Sequence Diagram Examples: REST API Validation

Use this Mermaid sequence diagram examples pattern when a client request passes through authentication, input validation, business logic, and persistence. The alternatives make the externally visible status codes explicit.

sequenceDiagram
    autonumber
    actor Client
    participant API
    participant Auth
    participant Orders
    participant DB as Orders Database

    Client->>API: POST /orders
    API->>Auth: Validate bearer token
    Auth-->>API: User identity
    API->>API: Validate request body
    alt Request is invalid
        API-->>Client: 400 Validation errors
    else Request is valid
        API->>Orders: Create order
        Orders->>DB: Insert order
        DB-->>Orders: Order ID
        Orders-->>API: Created order
        API-->>Client: 201 Created
    end

Adapt this Mermaid sequence diagram examples template by changing the failure branches first. A design review usually learns more from authentication failure, validation failure, and persistence failure than from another success message.

Mermaid Sequence Diagram Examples: Browser Login

This Mermaid sequence diagram examples template separates the browser, application, and identity provider. It shows the authorization redirect and the server-to-server code exchange without placing a token directly in the initial browser redirect.

sequenceDiagram
    autonumber
    actor User
    participant Browser
    participant App as Web Application
    participant IdP as Identity Provider

    User->>Browser: Choose Sign in
    Browser->>App: GET /login
    App-->>Browser: Redirect to authorization endpoint
    Browser->>IdP: Authorization request
    IdP-->>Browser: Show authentication prompt
    User->>IdP: Authenticate and consent
    IdP-->>Browser: Redirect with authorization code
    Browser->>App: GET /callback?code=...
    App->>IdP: Exchange code for tokens
    IdP-->>App: ID token and access token
    App-->>Browser: Set application session
    Browser-->>User: Show signed-in page

This Mermaid sequence diagram examples template intentionally omits provider-specific parameters. Add state, nonce, PKCE, cookie properties, and error responses only when the diagram is paired with the corresponding security requirements.

Mermaid Sequence Diagram Examples: Database Transaction

This Mermaid sequence diagram examples template can show transaction boundaries and participants, but it cannot prove isolation or atomicity. Use a note for the invariant and keep the commit or rollback result visible.

sequenceDiagram
    autonumber
    participant API as Transfer API
    participant Service as Transfer Service
    participant DB as Accounts Database
    participant Events as Outbox Publisher

    API->>Service: Transfer funds
    Service->>DB: Begin transaction
    Note over Service,DB: Balance update and outbox insert share one transaction
    Service->>DB: Debit source account
    Service->>DB: Credit destination account
    Service->>DB: Insert TransferCompleted outbox row
    alt Every statement succeeds
        Service->>DB: Commit transaction
        DB-->>Service: Commit confirmed
        Service-->>API: Transfer accepted
        Events->>DB: Read unpublished outbox rows
        DB-->>Events: TransferCompleted
    else A statement fails
        Service->>DB: Roll back transaction
        DB-->>Service: Rollback confirmed
        Service-->>API: Transfer rejected
    end

When adapting Mermaid sequence diagram examples, name in-process event publication accordingly. If a separate worker polls the outbox, show it as a separate participant so readers do not assume the event is published before the API responds.

Mermaid Sequence Diagram Examples: Background Job

This Mermaid sequence diagram examples template uses an open arrow for queued or asynchronous work and a separate status request for eventual completion. This prevents a diagram from implying that an HTTP request stays open while a long job runs.

sequenceDiagram
    autonumber
    actor User
    participant UI
    participant API
    participant Queue
    participant Worker
    participant Store as Result Store

    User->>UI: Request report
    UI->>API: POST /reports
    API-)Queue: Enqueue report job
    API-->>UI: 202 Accepted (report-42)
    Queue-)Worker: Deliver job
    Worker->>Store: Save generated report
    Store-->>Worker: Download key
    Worker->>API: Mark report ready
    UI->>API: GET /reports/report-42
    API-->>UI: Ready with download URL
    UI-->>User: Show download action

Extend Mermaid sequence diagram examples with redelivery, dead-letter handling, or cancellation only if those behaviors matter to the reader. For retry mechanics, continue with the loops and control-flow guide.

Mermaid Sequence Diagram Examples: Webhook Retry

This Mermaid sequence diagram examples template shows both the sender's retry rule and the receiver's idempotency behavior. A retry diagram that omits duplicate handling can encourage an unsafe consumer implementation.

sequenceDiagram
    autonumber
    participant Sender as Webhook Sender
    participant Receiver as Customer Endpoint
    participant DB as Delivery Store

    Sender->>DB: Create delivery with event ID
    loop Up to 3 attempts with backoff
        Sender->>Receiver: POST event with event ID
        alt Receiver accepts event
            Receiver-->>Sender: 2xx response
            Sender->>DB: Mark delivery complete
        else Timeout or retryable response
            Receiver-->>Sender: Timeout or 5xx
            Sender->>DB: Record failed attempt
        else Permanent rejection
            Receiver-->>Sender: Non-retryable 4xx
            Sender->>DB: Mark delivery rejected
        end
    end

In Mermaid sequence diagram examples, loop visualizes the retry window but does not execute the stop condition. State the exact retryable statuses, backoff schedule, signature validation, and maximum delivery age in the surrounding API documentation.

Mermaid Sequence Diagram Examples: Cache-Aside Read

This Mermaid sequence diagram examples template clarifies whether the application, cache, or database owns each action. It also makes the cache-miss path distinct from the fast path.

sequenceDiagram
    autonumber
    actor Client
    participant API
    participant Cache
    participant DB as Product Database

    Client->>API: GET /products/42
    API->>Cache: Get product:42
    alt Cache hit
        Cache-->>API: Cached product
        API-->>Client: 200 Product
    else Cache miss
        Cache-->>API: Not found
        API->>DB: Select product 42
        DB-->>API: Product row
        API->>Cache: Store product with TTL
        API-->>Client: 200 Product
    end

When adapting Mermaid sequence diagram examples, create a separate write-path diagram if stale data or cache invalidation is the main problem. Combining read-through, write-through, eviction, and recovery in one view usually hides the behavior the reader needs to verify.

Make Mermaid Sequence Diagram Examples Accurate

Before publishing Mermaid sequence diagram examples, review five things:

  1. Trigger: Identify the user action, event, or schedule that begins the interaction.
  2. Ownership: Give every decision to the participant that really makes it.
  3. Durability: Show the write that makes an outcome persistent, not just an in-memory call.
  4. Failure: Include the most important alternative, timeout, or early exit.
  5. Observable result: End with the response, event, stored state, or user-visible change that proves the interaction completed.

Mermaid Sequence Diagram Examples Source Checks

Use aliases to keep Mermaid sequence diagram examples readable while displaying full service names. Use dashed arrows consistently for responses and open arrows for asynchronous delivery.

Mermaid Sequence Diagram Examples Consistency Checks

If several Mermaid sequence diagram examples describe the same system, keep participant names stable so readers do not have to relearn the vocabulary.

Keep Mermaid Sequence Diagram Examples Focused

Mermaid sequence diagram examples should each answer one behavioral question. Split the source when it tries to show login, authorization, order creation, payment, fulfillment, and notification as one continuous interaction. Smaller diagrams are easier to review and less likely to become stale.

For foundational Mermaid sequence diagram examples syntax, return to the Mermaid Sequence Diagram tutorial. To organize complex branches, use the control-flow guide. When the interaction is correct but difficult to read, apply the styling and readability techniques. To place a tested example in repository documentation, follow Mermaid Sequence Diagrams in Markdown.