Archgram.ioA class diagram shows what exists. A sequence diagram shows what happens, in order, between the parts of a system. That makes it the most useful picture for designing an API: you can see who calls whom, what is synchronous, where a failure can occur and what the user is waiting for. This guide builds one in Mermaid, step by step.
The basics
Name the participants, then write one line per message. ->> is a call, and -->> is a reply.
A login request
Show the branches that matter
A diagram with only the happy path hides the interesting decisions. Use alt for either/or, opt for optional steps and loop for repetition.
Handling a wrong password
Make time and cost visible
- Activations (
activate/deactivate, or+and-on arrows) show how long a participant is busy, which exposes long synchronous chains. - Notes carry the facts the arrows cannot: timeouts, retries, idempotency keys.
- Async messages deserve a different arrow than calls the user waits on.
-)draws an open arrow for fire-and-forget.
A synchronous call with an asynchronous follow-up
Keep them useful
- One scenario per diagram. "Checkout, card declined" is one diagram, not a section of a bigger one.
- Limit to about six participants. More than that, split the flow or group services.
- Name messages with the real call (
POST /orders), so the diagram and the API stay in step. - Keep the source in the repository next to the API spec, and update both in the same pull request.
In Archgram you can edit sequence diagrams as text or through a form, restyle them, or ask the AI to draft one from a sentence like "login with email and password, lock the account after five failures". Sequence diagrams also convert to D2 and PlantUML if your documentation uses those. Open the editor to start.