Skip to main content

API Sequence Diagrams in Confluence with Mermaid (Copy-Paste)

· 5 min read
NGPilot

The integration doc says "the client calls the API, the API validates and responds" — four words, zero contracts, and the onboarding engineer asks "with what headers, in what order, and what if auth fails?" The code has the truth; the wiki has a paragraph. An API that can't be read as a transcript is an API nobody can safely operate.

Quick answer: document API flows in Confluence as Mermaid — sequenceDiagram for request/response order, packet-beta for wire-format frames, ZenUML for branch-heavy async flows — rendered by Mermaid Plus for Confluence. Each diagram type answers a different reader: what order, what's on the wire, what branches. This post gives you three copy-paste examples.

Why an API doc is a transcript, not a paragraph​

Three readers need three views of the same integration, and Mermaid gives each its own shape:

  • The order reader needs a sequenceDiagram — who calls whom, in what order, with which payloads. The alt/else branches carry the failure behavior.
  • The wire reader needs a packet diagram — the actual byte layout of a frame, field widths and all. Good for protocols, TLS records, coarse protocol headers.
  • The logic reader needs ZenUML — the interaction as statement blocks, so branch-heavy async flows read like pseudocode.

The point is the shape matches the question, and each shape is text the review can edit next to the code change that invalidates it.

Copy-paste 1: the request trace as a sequence​

An order placement across client → gateway → service → database, with the failure branch drawn (the runbook version):

sequenceDiagram
  participant C as Client
  participant G as Gateway
  participant S as Service
  participant DB as Database
  C->>G: POST /orders
  G->>G: auth + TLS check
  G->>S: forward with idempotency key
  alt validated
    S->>DB: INSERT order
    DB-->>S: 201 persisted
    S-->>C: 201 with order id
  else rejected
    S-->>C: 422 with errors
  end

Rendered Mermaid diagram

Read it as a transcript: the client's POST reaches the gateway, the gateway authenticates, the service validates and the transaction is either committed (201) or rejected (422). The alt/else block is the runbook's "what happens on a bad payload" — callers trust a diagram that documents the failure too.

Copy-paste 2: the wire frame as a packet diagram​

When the doc must show the byte layout — a protocol header, a TLS record, a coarse frame — the packet diagram puts field names over field widths, like a memory map of the on-wire format:

packet-beta
  title TCP segment
  0-15: "Source port"
  16-31: "Destination port"
  32-63: "Sequence number"
  64-95: "Acknowledgement"
  96-127: "Flags"
  128-158: "Window"
  159-190: "Checksum + Urgent"

TCP segment

Each field is named and sized; the reader sees the header layout without opening a packet decoder. For a custom protocol or a reverse-proxy header contract, this is the diagram that ends "where is the checksum" — forever.

Copy-paste 3: branch-heavy flow as ZenUML​

ZenUML writes interactions as statement blocks — when the flow's branching is the story (auth, retries, timeouts), the blocks read like the pseudocode of the behavior:

zenuml
  title Login flow
  Actor User
  Participant API
  Database Creds
  User->API: login(email, pass)
  API->Creds: lookup hash
  alt creds match
    Creds-->API: hash verified
    API-->User: access token
  else creds miss
    Creds-->API: no such account
    API-->User: 401 invalid
  end

Login flow

Like the sequence alt, the branches are explicit — but written as blocks that diff well and read down a page. Team rule of thumb: sequence for ordering, packet for wire, ZenUML for "the interaction is basically a decision tree." All three coexist on the API runbook page.

Choosing the API doc shape​

The questionDiagramWhen to use
In what order does the interaction happen?SequenceRequest traces, multi-service calls
What is on the wire, byte by byte?PacketProtocol headers, custom frames
How do the branches behave?ZenUMLAuth, retries, async decision trees
Where should work wait vs flow?FlowchartLong-running work, queues

The API runbook's neighbors are on the same wiki: the data shape exchanged by the calls as an ER schema and the deployment the services run on as a system architecture.

FAQ​

Does Confluence have a built-in API sequence diagram tool? No — Confluence has no native diagramming. Mermaid Plus for Confluence renders sequenceDiagram, packet-beta and ZenUML from editable text with a live preview.

Sequence, packet or ZenUML for an API doc? Sequence for request/response order, packet for the wire format, ZenUML for branch-heavy interactions that read best as blocks. An API runbook often holds all three.

How do I show failure handling in a sequence diagram? Wrap the branch in alt ... else ... end — success in the alt body, failure in the else body. The runbook's error behavior becomes a drawn part of the flow.

Can I keep a long API sequence diagram readable? Split by endpoint or critical path, limit participants to what that flow touches, and put invariants in note lines. Small clear transcripts beat a wide wall of arrows.

Render every Mermaid diagram type — sequence, packet, ZenUML, ER, C4 and 24 more — in Mermaid Plus for Confluence, free for up to 10 users.

Try Mermaid Plus for Confluence

All 29 Mermaid diagram types with live preview and one-click templates — free for up to 10 users.

Get it on the Atlassian Marketplace

Related guides