Flowchartio
Sign inTry it freeTry free

API and software flows

Documenting an API integration workflow

An 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.

By Flowchartio · Updated · 2 min read

What to include

  • Actors as lanes: user, frontend, your backend, each third-party service.
  • Calls in order, labelled with method and path.
  • Decisions on responses: success, client error, server error, timeout.
  • Retries and their limits.
  • Asynchronous steps: webhooks, polling, queues.
  • End states: what the user sees and what is stored in each outcome.

Example: card payment

  1. Frontend: customer confirms the order.
  2. Backend: create a payment with the provider (POST /payments).
  3. Decision: response?
    • Created → wait for confirmation.
    • Declined → show "card declined", end.
    • Timeout or server error → retry.
  4. Retry, up to 3 times with an increasing delay; then mark the order "payment pending" and alert support.
  5. Provider: sends a webhook when the payment succeeds or fails.
  6. Backend: verify the webhook signature, update the order, send the receipt.

Drawn in swimlanes, the chart makes clear that the order status depends on the webhook, not on the first response, which is a frequent source of bugs.

Show retries correctly

A retry is a loop, and every loop needs an exit, as explained in decisions and loops. Write the limit on the chart ("max 3 attempts") and draw what happens after the last failure. If a call can be retried safely, note how idempotency is guaranteed, for example with an idempotency key, so readers know duplicates are handled.

Webhooks and waiting

Represent the wait explicitly with a delay step ("Wait for provider webhook") and a timeout branch ("No webhook after 15 minutes → query payment status"). Without the timeout, the chart implies the system can wait forever.

Flowchart, sequence diagram, or both

The flowchart answers "what happens in each case?". A sequence diagram answers "who calls whom, in what order?". For complex integrations, keep both side by side in the repository, as Mermaid code on GitHub.

Start from the spec

If the third-party API publishes an OpenAPI file, import it to get exact endpoint names on each automated step; see OpenAPI to flowchart. For login, sign-up and token refresh, the dedicated guide on authentication flows lists the branches people usually forget.

Draft your integration flowchart.

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