How to Document APIs with Diagrams

Good API documentation tells developers what an endpoint does, what parameters it accepts, and what it returns. Great API documentation shows them how the pieces fit together. A well-placed diagram can communicate in seconds what paragraphs of prose struggle to explain: which services talk to each other, what order requests happen in, how authentication flows through the system, and what the underlying data model looks like.

This article covers four types of diagrams that belong in every API documentation set, with practical Mermaid.js examples you can copy and adapt.

Why API Documentation Needs Visuals

Text-based API references -- the kind generated by Swagger or Redoc -- are essential, but they describe each endpoint in isolation. They answer "what does this one endpoint do?" but not "how do these ten endpoints work together to complete a purchase?" Diagrams bridge that gap.

Sequence diagrams show the order of requests across multiple services, making integration logic explicit.
Flowcharts map decision trees for authentication, error handling, and retry logic.
Entity-relationship diagrams reveal the data model behind the API, so developers know what to expect in nested responses.
Architecture diagrams provide the big picture: API gateways, load balancers, microservices, and data stores.

Together, these four diagram types transform a reference manual into a developer guide.

Sequence Diagrams for Request Flows

Sequence diagrams are the single most useful visual for API documentation. They show exactly which actor sends which request, in what order, and what comes back. Here is a common pattern: a client authenticating via OAuth 2.0 and then fetching a protected resource.

sequenceDiagram
    participant Client
    participant AuthServer
    participant API

    Client->>AuthServer: POST /oauth/token (credentials)
    AuthServer-->>Client: 200 { access_token, expires_in }

    Client->>API: GET /users/me (Bearer token)
    API->>AuthServer: Validate token
    AuthServer-->>API: Token valid, scopes: [read]
    API-->>Client: 200 { id, name, email }

This diagram communicates several things that pure endpoint docs cannot: the client must hit the auth server before the API, the API validates the token by calling back to the auth server, and the response includes scope information that controls what the client can access.

Webhooks and Async Flows

APIs that use webhooks or asynchronous processing are especially hard to document with text alone. A sequence diagram makes the flow intuitive:

sequenceDiagram
    participant Client
    participant API
    participant Worker
    participant Webhook

    Client->>API: POST /exports { format: "csv" }
    API-->>Client: 202 { job_id, status: "queued" }

    API->>Worker: Enqueue export job
    Worker->>Worker: Process export

    Client->>API: GET /exports/{job_id}
    API-->>Client: 200 { status: "processing" }

    Worker->>API: Job complete, file ready
    API->>Webhook: POST callback_url { job_id, download_url }
    Webhook-->>API: 200 OK

Without this diagram, a developer would need to piece together the async flow from three separate endpoint descriptions and a webhook specification. The sequence diagram shows the full lifecycle in one view.

Flowcharts for Auth and Error Handling

Not every API interaction is a straight line. Authentication checks, rate limiting, permission logic, and error recovery all involve branching decisions. Flowcharts are the right tool for these.

flowchart TD
    A[Incoming Request] --> B{Has Authorization header?}
    B -- No --> C[Return 401 Unauthorized]
    B -- Yes --> D{Token format valid?}
    D -- No --> E[Return 401 Invalid Token]
    D -- Yes --> F{Token expired?}
    F -- Yes --> G[Return 401 Token Expired]
    F -- No --> H{Has required scope?}
    H -- No --> I[Return 403 Forbidden]
    H -- Yes --> J[Process Request]
    J --> K{Business logic error?}
    K -- Yes --> L[Return 4xx with error body]
    K -- No --> M[Return 2xx with data]

This flowchart serves double duty. For API consumers, it explains exactly which error code to expect for each failure mode. For backend developers, it documents the middleware pipeline. Put it at the top of your authentication guide, and most "why am I getting a 403?" support questions disappear.

Retry and Rate Limit Logic

If your API enforces rate limits, document the consumer's retry strategy as a flowchart:

flowchart TD
    A[Send API Request] --> B{Response status?}
    B -- 200-299 --> C[Success - process response]
    B -- 429 --> D[Read Retry-After header]
    D --> E[Wait specified duration]
    E --> A
    B -- 500-599 --> F{Retry count < 3?}
    F -- Yes --> G[Exponential backoff wait]
    G --> A
    F -- No --> H[Log error, alert, fail gracefully]

ERDs for Data Models

When your API returns nested objects -- an order containing line items, each referencing a product and a customer -- an entity-relationship diagram makes the structure immediately clear.

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    LINE_ITEM }o--|| PRODUCT : references
    PRODUCT }o--|| CATEGORY : "belongs to"

    CUSTOMER {
        string id PK
        string name
        string email
        datetime created_at
    }

    ORDER {
        string id PK
        string customer_id FK
        string status
        decimal total
        datetime ordered_at
    }

    LINE_ITEM {
        string id PK
        string order_id FK
        string product_id FK
        int quantity
        decimal unit_price
    }

    PRODUCT {
        string id PK
        string category_id FK
        string name
        decimal price
        boolean active
    }

Place this diagram in the "Data Models" section of your docs. Developers integrating with your API can see at a glance that an ORDER has many LINE_ITEMs, each LINE_ITEM references one PRODUCT, and a CUSTOMER can have many ORDERs. The field names and types map directly to what they will see in API responses.

Architecture Diagrams for the Big Picture

Before diving into individual endpoints, developers need to understand the system they are integrating with. An architecture diagram answers the questions that endpoint documentation cannot: Where does my request actually go? What sits between my client and the database?

flowchart LR
    Client[Client App] --> GW[API Gateway]
    GW --> Auth[Auth Service]
    GW --> Users[User Service]
    GW --> Orders[Order Service]
    GW --> Notify[Notification Service]

    Auth --> DB1[(Auth DB)]
    Users --> DB2[(User DB)]
    Orders --> DB3[(Order DB)]
    Orders --> Queue[Message Queue]
    Queue --> Notify
    Notify --> Email[Email Provider]
    Notify --> Push[Push Service]

This diagram tells a developer that the API Gateway is the single entry point, that authentication is handled by a separate service, that orders communicate with notifications via a message queue, and that notifications fan out to email and push channels. That context makes every endpoint in the docs easier to understand.

Integration Tips

Embed Diagrams in Your Existing Docs

If you use Markdown-based documentation (GitBook, Docusaurus, MkDocs, or GitHub wikis), you can embed Mermaid code blocks directly. GitHub renders Mermaid natively in Markdown files, so diagrams in your README stay up to date with zero build step.

Link Diagrams to the Editor

For interactive documentation, generate a SimpleMermaid share link for each diagram and embed it in your docs. Developers can click through to modify the diagram, explore variations, and export to PNG or SVG for presentations.

Version Diagrams with Your Code

Store .mmd files in the same repository as your API source code. When an endpoint changes, the diagram diff shows up in the same pull request. This practice, known as diagrams as code, keeps documentation honest.

Layer Your Documentation

Use the four diagram types as layers of increasing detail:

Architecture diagram -- the 10,000-foot view for onboarding new developers.
Sequence diagrams -- the workflow view for each major use case.
Flowcharts -- the decision view for error handling and auth.
ERDs -- the data view for understanding response shapes and relationships.

Tip: Start with one sequence diagram for your most-used API flow. That single visual will generate more positive developer feedback than pages of new text documentation. You can build out the other diagram types over time.

Getting Started

Pick the API flow that generates the most support questions. Open the SimpleMermaid editor, paste in a sequence diagram skeleton, and fill in the participants and messages. Share the link with your team for review. Once approved, embed the Mermaid code block in your documentation source. Repeat for auth flows, error handling, and data models until your API documentation is genuinely visual.

Diagrams do not replace text documentation -- they complement it. The combination of a clear sequence diagram and a detailed endpoint reference is greater than the sum of its parts.

Create Your API Diagrams

Open the SimpleMermaid editor and start visualizing your API flows today.

Open the Editor