Programmer-friendly API documentation should always include a substantial overview or programmer’s guide section that provides context to the API reference. One of the most important sections in this API doc is the part that explains the relationships between the various components in the deployment. Not just the inputs and outputs of your endpoints, but rather the flow of calls between all the various services in the deployment. You need to describe the order of the calls, the dependencies between the components at each stage, etc.
That’s where sequence diagrams come in. They turn complex request flows into something visual, intuitive, and instantly understandable. Whether you're writing REST, GraphQL, or event-driven API docs, adding sequence diagrams can make the difference between “uh… what?” and “ah, got it.”
What is a sequence diagram?
A sequence diagram is a type of UML (Unified Modeling Language) diagram that shows how different components interact over time. Think of it as a timeline of API calls, who initiates a request, who responds, and what happens in between.
Here’s a simple example using Mermaid syntax, which many doc tools (like GitHub, Notion, and MkDocs) already support:
participant Client
participant API
participant Database
Client->>API: POST /login
API->>Database: Verify user credentials
Database-->>API: Return user record
API-->>Client: 200 OK + JWT token
That’s it, four lines of text that explain an entire authentication flow.
Why use sequence diagrams in API docs?
They clarify complex interactions - instead of describing multiple steps in a paragraph, you show them visually.
They reduce support questions - developers can see exactly what happens at each stage of the flow.
They support multiple endpoints - you can use the same diagram concept across multiple endpoints or even microservices. This provides a better understanding of the relationship between the endpoints and their methods.
How to create a sequence diagram in your API doc - a real world example
In one of the projects in my technical writing agency, I had to document the API endpoints of a fraud detection solution. You can see the live example of the API documentation with the diagrams. This specific diagram was created using the free Sequence Diagram tool. But there are also other tools, as described below.
Create the entities - in this case there is a merchant app, which communicates with the merchant server. The merchant server communicates with my client, nSure.ai, service to receive a response for the fraud check. As part of the check nSure.ai’s service communicates with a payment processor to receive a signal that is used in the check. If the transaction occurs, it communicates also with the inventory system.
Draw the steps - a step can describe something that occurred offline or online. For example, a purchase of a product or a payment. In addition, steps represent the API calls and their methods (e.g. GET, PUT, etc.). Each step should include the call to the entity and the response. Try to simplify this by not including all the possible responses (such as communication error responses etc.), as the idea here is to understand the flow. The details are found in the reference section.
Annotate optional flows - if a part of the flow is optional, annotate it in an OPT box.
Annotate alternative flows - if a part of the flow is optional, annotate it in an ALT box.
Annotate the end of a process - if one of the processes in the flow hits a dead end, annotate it as “End Process”.
Write a worded description - this is optional but recommended. You should write a step-by-step description of the flow, while naming all the endpoints and methods used.
Tools for creating sequence diagrams
If I am missing anyone, please let me know in the comments.
https://sequencediagram.org/ - free tool. GUI and text-base. Browser-based live editor with real-time preview and easy sharing.
Mermaid.js - Text-based. Works in Markdown and static doc sites.
PlantUML - Good for complex enterprise diagrams
WebSequenceDiagrams.com - Fast drag-and-drop editor.
Draw.io (diagrams.net) - Exports to SVG for embedding.
Best practices for technical writers
Keep it simple. Don’t show every internal service. Focus on what the reader needs to know.
Use consistent participant names. e.g., “Client,” “API,” “DB,” “Auth Service.”
Explain the diagram below it. Treat visuals as complementary, not replacements for explanations.
Version control your diagrams. When APIs change, diagrams should too, especially if auto-generated from source.
How to embed mermaid in your docs
If you’re using Markdown-based documentation (like Docusaurus, MkDocs, or GitBook), you can usually add Mermaid blocks directly.
If your system doesn’t support Mermaid out of the box, check if your static site generator offers a plugin, or simply export diagrams as SVG files.
About the Author
I’m a technical writer and founder of Writec – Technical & Marketing Writing, a technical writing agency that helps tech companies explain complex systems with clarity and style. If you enjoyed this post, follow me on DEV or LinkedIn for more insights on technical documentation, UX writing, and API storytelling.
Top comments (1)
Let me know if I missed a tool.