API Flow Diagram Guide

An API flow diagram shows what actually happens between the moment a client sends a request and the moment it gets a response: which services get involved, in what order, and what each one sends back. It is the picture your API reference does not give you — a reference documents endpoints one at a time, and a single endpoint is almost never the whole story.

The right notation for this is a sequence diagram, not a flowchart. The reason is structural: an API call is a conversation between several parties (client, gateway, auth service, your service, a database, a third-party provider), and the interesting information is who talks to whom, in what order. A sequence diagram puts each party on its own vertical lifeline and draws time downward, so the ordering is the shape of the picture. A flowchart has one implicit actor and no time axis, so the moment you have three services it starts lying.

Where an API flow diagram earns its keep is the unhappy paths. The success path is usually obvious and everyone already agrees on it. What nobody agrees on is: which service returns the 401 — the gateway or the auth service? If the payment provider times out, do we retry? Who is responsible for the 409? Those disagreements are invisible in prose and unmissable in a diagram, because an unlabelled arrow is a hole you can point at.

One diagram per flow, not per endpoint. "Create an order" is a flow; POST /v1/orders is one arrow inside it.

A diagram that only draws the success path is decoration. Five things make it load-bearing:

Here is the smallest diagram that satisfies the first three. It is the skeleton every example below grows out of — four participants, explicit paths, explicit status code.

Three steps. Do them in this order — people who start by drawing arrows always end up redrawing.

Write down everything the request touches. Then remove any participant that never sends a message of its own — if a component only sits between two others and forwards bytes unchanged, it is infrastructure, not a participant, and drawing it adds a lifeline without adding information.

Four to six participants is the sweet spot. Past seven the diagram gets wider than a screen and people stop reading it. If you genuinely have nine, that is a signal to split the flow: draw "client → gateway → service" as one diagram and "service → downstream fan-out" as another, and link them.

Get the success path down first — it is usually five to eight arrows and takes two minutes. Then go back over it and, for each arrow, ask the same three questions:

What if this times out? Not "what if it returns an error" — timeouts are worse, because you do not know whether the other side did the work. That distinction is the whole subject of the second example below.

What if this returns 4xx? Which of the two adjacent participants translates it, and into what? A downstream 404 surfacing to the client as a 500 is one of the most common API bugs, and it is visible in a diagram the moment you draw both arrows.

Can this be retried safely? If yes, say so on the arrow. If not, the diagram needs to show what makes it safe — an idempotency key, a dedup table, a state check.

Each "yes, that can happen" becomes an alt block. Three or four alt blocks is a healthy diagram; zero means you drew the brochure version.

Describe the call in plain sentences and let text2diagram lay it out — "a client posts to the gateway, the gateway checks the token with the auth service, then forwards to the orders service, which writes to Postgres and returns 201; if the token is expired the gateway returns 401" comes back as an editable sequenceDiagram.

Faster still: open any example below in the editor and rename the participants. The arrangement of arrows is the part that took thought; the names are the part you can retype in thirty seconds.

Three flows that cover most of what a real API does: a synchronous request with auth, a call that fails in the worst possible way, and an operation too slow to answer inline.

The thing to copy here is not the shape — it is that both failure branches are drawn, and each one names the participant that produces the status code. The gateway returns the 401 (the auth service only says "rejected"); the orders service returns the 409 (the database only says "duplicate key"). Writing that down settles an argument that otherwise gets re-litigated every few months.

autonumber is worth turning on for any diagram over about eight arrows — it gives reviewers something to point at.

This is the flow most worth having on a wall. A timeout is not an error — an error tells you the work did not happen, a timeout tells you nothing. The dashed --x arrow is Mermaid's notation for a message that never arrived, and it is doing real work here: it visually distinguishes "the provider said no" from "we have no idea".

The resolution is the two arrows after it: look before you retry. Query by idempotency key first, retry only if the lookup comes back empty. Teams that skip that lookup double-charge customers, and the reason it gets skipped is almost always that nobody drew this picture.

When the work takes longer than a request should, the API stops being a question-and-answer and becomes two separate conversations. The diagram has to show the seam: the 202 Accepted goes back before any of the real work happens, and everything after it is a different flow that your caller does not control.

Two details people leave out and then regret. First, the retry schedule belongs in the diagram (that Note is not decoration — "how many times do we retry a customer's webhook" is a question support will ask). Second, the customer's endpoint is a participant like any other, which means it gets failure branches too. It is the least reliable box on the page and the one most often drawn as if it always returns 200.