Guides
Flowcharts for APIs and software flows
Developers use flowcharts to document what code and services do in order: the calls of an API integration, the branches of an algorithm, the paths of a sign-up or payment flow. A good technical flowchart shows decisions and error paths, and names the endpoint or function behind each automated step.
What flowcharts are good at in software
Code tells you exactly what happens, but only to someone who reads all of it. A flowchart gives the shape of the behaviour in one view: the main path, the branches, the error handling, and the points where the system waits or calls another service. That helps when:
- onboarding a developer onto a service,
- reviewing a design before writing code,
- explaining a behaviour to product, support or security teams,
- debugging a flow that fails only in some branches.
Flowchart or sequence diagram?
Use a sequence diagram when the question is "which component calls which, in what order?": it shows messages between participants over time. Use a flowchart when the question is "what happens in which case?": it shows decisions and outcomes. Many integrations deserve both. Both can be written in Mermaid.
Typical technical flowcharts
- API integrations: the order of calls, retries and error handling; see documenting an API integration workflow.
- From a specification: an OpenAPI or Swagger file lists the endpoints, and a flowchart puts them in business order; see OpenAPI to flowchart. The same works for SOAP services and their WSDL.
- Algorithms: loops and conditions before or after coding; see algorithm flowcharts and pseudocode.
- Authentication: sign-up, login, verification and password reset, with their many failure branches; see sign-up and login flowcharts.
Make technical flowcharts useful
- Name the real thing: put the endpoint (
POST /payments) or function name on automated steps. - Show failures: timeouts, 4xx and 5xx responses, retries and their limits. The happy path alone hides the interesting part.
- Separate actors: user, frontend, backend, third-party API as lanes, so responsibilities are clear.
- Keep it next to the code: as Mermaid in the repository, updated in the same pull request as the behaviour; see Mermaid on GitHub.
How detailed should it be?
Aim for the level a new team member needs to understand the behaviour, not a line-by-line copy of the code. A good test: every decision on the chart corresponds to a branch that changes what the user or another system experiences. Internal details, such as which helper function formats a date, belong in the code, not on the chart. When a flow is too large, split it: one chart for the main path, one per significant sub-flow. Link the charts to each other so readers can move between levels of detail.
Generate the first draft
Describe the flow in a few sentences and attach the API specification. Flowchartio drafts the chart with endpoints bound to the automated steps, and you refine it in conversation before exporting to Mermaid or SVG. Read how text-to-flowchart AI works to know what to expect, or try it with your spec.
In this guide
Each article goes deeper into one part of the topic.
- From an OpenAPI or Swagger file to a flowchartAn OpenAPI (or Swagger) file lists what an API can do, but not in what order a process uses it. To get a useful flowchart, combine the file with a short description of the process: the description gives the order and the decisions, and the specification gives the exact endpoint for each automated step.
- Documenting an API integration workflowAn integration flowchart shows the order of API calls and, above all, what happens when they fail: timeouts, error responses, retries with limits, and asynchronous callbacks such as webhooks. Put each actor (your app, your backend, the third-party API) in its own lane.
- Algorithm flowcharts and pseudocodeAn algorithm flowchart represents a program’s logic with three building blocks: sequence (steps one after another), selection (a decision) and iteration (a loop). Each maps directly to pseudocode and code, which is why flowcharts are used to design and teach algorithms.
- Sign-up and login flowchartsAuthentication flows look simple on the happy path and get complicated in the branches: email already used, unverified accounts, wrong passwords, lockouts, multi-factor authentication and password resets. A flowchart per flow makes those branches, and the security decisions behind them, explicit.
- WSDL and SOAP services as flowchartsA WSDL file describes a SOAP web service: its operations, messages and endpoints. Like an OpenAPI file, it lists what the service can do but not in which order a process uses it, so combine it with a description of the process to get a flowchart where each automated step names its operation.
Turn your process into a flowchart
Describe it in a few sentences. Flowchartio draws the flowchart, then you refine it in conversation.
Generate a flowchart