Diagrams as Code with Mermaid

Sequence Diagrams for APIs

From space to time

In the previous submodule, you built diagrams where nodes sit in space and edges connect them. Sequence diagrams flip that: participants stand in columns, and messages travel horizontally across *time* — top to bottom. Same Mermaid tooling, very different mental model.

Every sequence diagram starts with sequenceDiagram on its own line. Everything after that is either a participant declaration or a message.

Participants and actors

Participants are the columns in your diagram. Declaring them explicitly before any messages is almost always worth it — it fixes the left-to-right column order, which is the first thing that makes or breaks readability:

sequenceDiagram
    participant Client
    participant API
    participant DB

Use actor instead of participant when you want a stick-figure symbol — the right call for a human at one end of the flow:

sequenceDiagram
    actor User
    participant Browser
    participant API

For long names, aliases keep message lines readable:

    participant A as Auth Service
    participant T as Token Store

After the alias, A and T are what you write in message lines. The diagram renders the full display names.

Column order matters. If your flow is Client → API → DB, declare them in that order. Swapping DB before API forces arrows to cross and the diagram immediately becomes confusing.

Arrow types

Four arrows cover almost every API scenario:

The practical convention: solid arrow going *forward*, dotted arrow coming *back*. Client->>API: GET /users and API-->>Client: 200 OK — one type per direction, consistently. --> and -> (filled-head variants) are older aliases; the open-head forms (->>, -->>) are current.

Activation boxes

Activation boxes show the window during which a participant is actively processing. Append + when sending a call to open the box on the receiver, and - when sending the reply to close it:

sequenceDiagram
    Client->>+API: GET /users
    API->>+DB: SELECT *
    DB-->>-API: rows
    API-->>-Client: 200 OK

When API calls DB while still activated itself, you get stacked boxes on the API column — an accurate visual showing that API is suspended waiting on DB. The +/- shorthand is almost always cleaner than the explicit activate/deactivate keywords.

Alt, opt, and loop

These three blocks map to the control-flow patterns you write code for every day.

alt — branching

alt token valid
    API-->>Client: 200 OK
else token expired
    API-->>Client: 401 Unauthorized
end

opt — optional path (runs only sometimes)

opt cache hit
    API-->>Client: 200 (from cache)
end

loop — repeated messages

loop poll every 2 seconds
    Client->>API: GET /job/status
    API-->>Client: 202 In progress
end

All three share the same structure: keyword label … end. The end keyword that closes each block is why you must never let the word end appear *unquoted* inside a label — exactly the same rule from the flowchart submodule. If your label is call endpoint, write "call endpoint" or rephrase it.

Notes

Notes annotate one participant or span two:

Note right of Client: Stores token in memory
Note over API,DB: Both services must be in the same region

Note right of / Note left of attach to one column. Note over A,B draws a box spanning both — good for constraints that apply to the whole interaction. Keep them to a single short line; anything longer belongs in prose, not the diagram.

Autonumber

Add autonumber right after sequenceDiagram to label every message automatically:

sequenceDiagram
    autonumber
    Client->>+API: GET /profile
    API-->>-Client: 200

This makes cross-referencing easy in written docs — "at step 3, the token is validated." You can start from a given number (autonumber 5) or set an increment (autonumber 1 2 produces 1, 3, 5…), useful when a diagram is the second of two connected diagrams in the same doc.

Worked example: OAuth token exchange

Here's a realistic auth handshake — user, browser, auth service, and resource API — combining most of what's covered above:

Things to notice:

• Participants declared explicitly so column order is intentional.
• Activation boxes on AuthSvc and ResourceAPI show exactly when each is processing.
• The alt block cleanly separates the success path from the 401 branch without duplicating any arrows.
• The Note documents the token TTL without cluttering message flow.
• Message labels avoid slashes and parentheses in the critical node names — zero quoting needed here.

Keeping it from turning to noise

A sequence diagram with more than ~7 participants or ~20 messages becomes unreadable fast. Three practical rules:

1. One scenario per diagram. Show the happy path in one diagram; show error branches in a second. An alt block with four branches is almost always better split into two focused diagrams.

2. Hide internal plumbing from consumer-facing docs. If you're documenting a public API, omit the DB calls — consumers care about the Client↔API contract, not how data is fetched internally.

3. Name participants specifically. Service is noise. PaymentService is useful. Same effort to type, much better to read in six months.

Quick check

Try these in mermaid.live:

1. Draw three participants — Browser, API, DB — with +/- activation boxes and autonumber.

2. Add an alt block: cache hit returns directly from API; cache miss queries DB.

3. Deliberately put endpoint unquoted in an alt label — watch the diagram break when the parser sees end. Then quote it to fix.

The next submodule covers class and ER diagrams. The quoting rules and the end gotcha carry over exactly — and you'll use the same participant-declaration thinking when defining entities and relationships.