How to Create a Sequence Diagram for an API Request: Examples and Templates

Overview

An API sequence diagram shows interactions in time order. Participants are placed across the top, usually from the caller on the left to internal services, data stores, and external systems on the right. Arrows represent requests, responses, events, or callbacks. The vertical direction represents time: messages near the top happen before messages farther down.

For a basic API request, the participants might be a browser or mobile client, an API gateway, an application service, an identity provider, and a database. A useful diagram does not need every implementation detail. It should show the decisions and boundaries that help a reader understand behavior, ownership, security, and failure handling.

Before drawing, define the question the diagram must answer. “What happens when a customer updates an address?” is more useful than “Document the API.” A focused API sequence diagram can then cover the endpoint, authentication, validation, service calls, persistence, response, and relevant alternatives without becoming a complete map of the system.

Choose a sequence diagram maker that matches the way your team maintains documentation. A visual editor can be convenient for collaborative workshops, while a diagram-as-code workflow can make diagrams easier to review beside API specifications and source changes. For a broader comparison of syntax-based options, see Mermaid vs PlantUML vs D2 vs Graphviz.

Checklist by scenario

REST API request

1. Start with the client or calling service and name the HTTP method and route, such as POST /orders.
2. Show the authentication step or indicate where a bearer token, session, signed request, or service credential is checked.
3. Separate transport validation from business validation. A malformed request and an unavailable product may produce different responses and follow different paths.
4. Show the application service, database, and any external dependency that affects the result.
5. Return the status outcome, response body at a useful level, and correlation or request identifier if it matters during support.
6. Add an alt path for common failures, such as unauthorized access, validation errors, a conflict, or a dependency timeout.

A compact REST template might look like this:

sequenceDiagram
  participant C as Client
  participant API as API Service
  participant DB as Database
  C->>API: POST /orders + access token
  API->>API: Authenticate and validate
  API->>DB: Insert order
  DB-->>API: Order ID
  API-->>C: 201 Created
  alt Invalid request
    API-->>C: 400 Validation error
  else Database unavailable
    API-->>C: 503 Retryable error
  end

GraphQL request

GraphQL diagrams should identify the client operation and the GraphQL endpoint, then make resolver behavior visible when it is important. Show whether resolvers call one service or fan out to several services. If nested fields can cause multiple data requests, represent that pattern rather than implying that one database call serves the entire query. Include authorization at the field or resolver boundary when permissions differ by field.

• Name the query or mutation and the requested fields.
• Show schema validation before resolver execution.
• Distinguish a complete response from a response containing both data and errors.
• Document batching, caching, or downstream calls only when they affect latency, correctness, or ownership.

Webhook delivery

A webhook sequence diagram should begin with the event-producing system and end with the subscriber’s acknowledgment. Include signature verification, timestamp or replay protection where applicable, idempotency handling, and delivery retries. The receiving system may acknowledge quickly and process the event later; show those as separate paths.

sequenceDiagram
  participant P as Event Producer
  participant W as Webhook Endpoint
  participant Q as Queue
  participant H as Handler
  P->>W: POST event + signature
  W->>W: Verify signature and event ID
  W->>Q: Enqueue event
  W-->>P: 202 Accepted
  Q->>H: Deliver event
  H->>H: Apply idempotent update
  alt Invalid signature
    W-->>P: 401 Unauthorized
  end

Event-driven or asynchronous request

For asynchronous work, distinguish the initial command from the later event. Show the client’s immediate acknowledgment, the broker or queue, the worker, and the eventual notification or status lookup. Mark retry and dead-letter behavior if operators need it to diagnose a stuck workflow. Do not draw an asynchronous message as though it were a synchronous response.

What to double-check

Use this review checklist before publishing an API sequence diagram:

• Participants: Does every actor, service, data store, queue, and external dependency have a clear name and responsibility?
• Direction: Is it obvious who initiates each message and whether the arrow is a request, response, event, or callback?
• Timing: Does vertical order reflect the actual interaction, including parallel calls and delayed work?
• Boundaries: Are trust boundaries, network boundaries, and ownership boundaries visible where they affect the design?
• Authentication: Does the diagram show where identity is established and where authorization is evaluated?
• Data: Are sensitive values abstracted? Use labels such as “access token” or “customer record” rather than copying real credentials or personal data.
• Failures: Are timeout, validation, authorization, dependency, and duplicate-message cases represented at the right level?
• Retries: Is the retry owner identified, and could a retry create a duplicate side effect?
• Consistency: Does the response accurately describe whether data is committed, queued, eventually consistent, or still being processed?
• Scope: Can a reader understand the main path without zooming into an unreadable wall of detail?

For database-heavy flows, pair the sequence diagram with a schema or ERD rather than placing every table and column in the interaction view. The database schema and ERD guide explains how to model those relationships separately. Likewise, use a system or C4 view when readers need the larger service landscape instead of endpoint-level timing.

Common mistakes

Showing only the happy path

A diagram that ends at “200 OK” may hide the behavior most useful during design review or incident analysis. Add only the failure paths that change the contract or operational response, but include them explicitly.

Confusing components with participants

One box should represent a meaningful interaction boundary. Splitting a single service into controllers, helpers, and repositories can obscure the API behavior unless the implementation detail is the subject of the diagram.

Mixing logical and physical views

A logical sequence can say “Orders Service” without naming every host or container. A deployment diagram can show nodes, regions, and network segments. Combining both views often creates labels that are difficult to maintain.

Leaving async behavior ambiguous

Use clear labels such as “enqueue,” “publish,” “acknowledge,” “poll status,” and “callback.” If processing continues after the HTTP response, draw the continuation separately.

Embedding secrets or unstable details

Never use production tokens, customer data, or copied payloads that contain sensitive values. Prefer representative fields and link to the API contract for the complete schema. Keep volatile implementation details in code or generated documentation when possible.

Publishing a diagram without ownership

Record the endpoint or workflow covered, the owning team, and the last review date. If the diagram is maintained as Markdown, keep it near the relevant documentation and review syntax changes with normal pull requests. This docs-as-code workflow for Mermaid diagrams offers a practical model for doing that.

When to revisit

Revisit an API sequence diagram whenever its underlying interaction changes, not merely on a fixed calendar. Update it when an endpoint changes authentication, validation, status codes, retry behavior, persistence, queueing, or downstream ownership. A new cache, message broker, webhook consumer, or asynchronous job may also change the story even when the public API remains stable.

Use the diagram during design reviews, incident follow-ups, onboarding, and seasonal planning cycles when traffic patterns or operational priorities may expose a previously minor path. Before a review, run the checklist above against current API contracts, service ownership, and failure handling. After a production issue, add the missing path only if it improves future understanding; avoid turning the diagram into an incident transcript.

To act now, choose one representative endpoint and create a first version with five elements: caller, API boundary, authentication or authorization step, primary data or service dependency, and response. Add one meaningful failure path, then ask the owning engineer to verify ordering and responsibility. Store the finished diagram beside the endpoint documentation, link to related ERD or architecture views, and assign a clear owner for the next change.