Mermaid Sequence Diagrams for APIs

Practical recommendation

Use participants for systems or roles, not every function. Label arrows with method, path, or event and responses with the important status or result.

Use alt blocks for authentication, validation, and service failures. Replace real tokens, account IDs, and customer values with synthetic labels before sharing.

Working example

sequenceDiagram
  participant QA
  participant Gateway
  participant Orders
  QA->>Gateway: GET /orders (synthetic token)
  Gateway->>Orders: Authorized request
  alt Orders available
    Orders-->>Gateway: 200 order list
    Gateway-->>QA: 200 JSON
  else Orders unavailable
    Orders-->>Gateway: timeout
    Gateway-->>QA: 503 problem detail
  end

Review checklist

• Participants have clear ownership.
• Requests and responses point in the correct direction.
• Important alternate paths are visible.
• No production credential or customer data appears.

Compatibility, security, and limitations

• A diagram is not a network trace and should not invent unseen calls.
• Dense payloads belong in separate examples.
• Async and retry behavior must be labeled explicitly.

Select the boundary shown by each arrow

Use participants for independently meaningful systems or roles: browser, gateway, identity provider, service, queue, and database. Avoid turning every internal function into a participant. Label calls with method/path or event name and responses with the status or outcome that matters to the investigation.

Activation bars and notes can clarify ownership, but a dense payload belongs in a linked code example. Tokens, cookies, customer identifiers, and production hostnames should be replaced with obvious synthetic labels before the diagram is pasted into a ticket.

Model failure and asynchronous behavior

An alt block is useful for authentication failure, validation rejection, dependency timeout, or retry exhaustion. Use loop only when repetition is part of the contract and label its limit. For asynchronous messages, show acknowledgement separately from eventual processing so readers do not infer a completed business action.

Validate the sequence against traces or implementation owners. A diagram should distinguish an observed call from a proposed design and must not invent services simply to make the picture feel complete.

References

• Mermaid Sequence Diagram Syntax
• OWASP Logging Cheat Sheet

FAQ

Related guides