Mermaid Sequence Diagrams for API and Service Calls

Sequence diagrams explain interaction order. They are a better fit than flowcharts when the central question is “who sends what to whom, and when?” Typical uses include browser-to-API calls, authentication handshakes, webhook delivery, queues, and service-to-service retries.

Declare participants with useful names

sequenceDiagram
  actor User
  participant Web as Web application
  participant API as Orders API
  participant DB as Database

  User->>Web: Submit order
  Web->>API: POST /orders
  API->>DB: Insert order
  DB-->>API: Order ID
  API-->>Web: 201 Created
  Web-->>User: Show confirmation

Aliases keep message statements compact while displaying readable labels. Use an actor for a human role and participants for software components. List them in the order that makes the dominant path easy to follow.

Distinguish calls from replies

Solid arrows are commonly used for requests or calls, while dotted arrows work well for replies. This is a communication convention rather than a guarantee of synchronous execution. If the distinction between blocking and asynchronous work matters, state it in the label or accompanying prose.

Show alternatives without duplicating diagrams

Use an alt block when two outcomes share the same context:

sequenceDiagram
  Client->>API: GET /profile
  alt token is valid
    API-->>Client: 200 Profile
  else token expired
    API-->>Client: 401 Unauthorized
  end

Use opt for an optional branch and loop for repeated interaction. Keep block labels about the condition, not the implementation. “Token is valid” is clearer than “if checkToken() returns true.”

Keep time and responsibility honest

A sequence diagram reads from top to bottom but is not automatically a performance timeline. Do not imply precise duration from vertical spacing. If latency matters, put measured values in message labels or a separate performance chart.

Also avoid a sequence diagram that tries to document every internal function call. Model interactions across meaningful boundaries. A focused diagram is easier to keep synchronized with the API contract and failure behavior.

Paste the example into the Mermaid diagram editor and replace one participant at a time with components from your system. Export SVG for documentation so text and lines remain sharp at different widths.