API flow testing: test the sequence, not just the endpoint

What an API flow test is

A flow is a sequence of API calls with data passed between them: sign in and keep the token, create an order and keep its id, fetch that order and check its status, update it, delete it. Each step depends on what earlier steps returned.

Single-endpoint tests can’t see the bugs that live between calls: an id that comes back in a field the next call doesn’t accept, a token that lacks a scope a later call needs, a list that doesn’t include the record you just created because of caching or a missing filter.

Designing a good flow

1. Start from a client’s task, not from the endpoint list: what does the frontend or the integration do, in which order?

2. Sign in as the role that does the task, the way that client signs in, and keep the token or cookies for the steps after it.

3. Pass values forward explicitly. A path like /orders/{order.id} or a body field that refers to an earlier answer documents the dependency and fails clearly when it breaks.

4. Make data unique per run: names and emails with a run id, so two runs, or a run and a person, never collide.

5. Check each step, and check the end state: after the update, does a fresh read show the new value?

6. Clean up what the flow created, also when a step in the middle failed.

What to check at each step

• Status: the code you expect, including refusals: a missing field should answer 422, another tenant’s record 403 or 404.
• Fields: ids exist, totals match, a status is not stuck at “pending”.
• Timing: a ceiling per step, so a slow query shows before it becomes an outage.
• Asynchronous effects: when something happens in the background (a job, a webhook, a payment that settles), poll a read until it shows the result, with a time limit, rather than sleeping a fixed time.

Keeping flows stable

• Rate limits: wait out a 429 with Retry-After instead of failing the run.
• No shared state: a flow that reads a record someone created by hand breaks when that record changes.
• One run at a time per flow: two copies of the same flow creating the same data at once produce errors that aren’t bugs.
• API changes: when the API changes, the flows that use the changed endpoints should be the first to know, not your users.

API flow testing in Journey Lanes

In Journey Lanes a flow is a graph of steps per role. The runner walks the steps in dependency order, fills path parameters from earlier answers, and generates request bodies from your entity shapes. Steps can refer to earlier answers with {{step-id.path}} and to this run’s own values with {{run.id}}, so data is unique per run.

Every step can carry checks on status, response time and fields. Reads can repeat until their checks pass for up to five minutes, 429 and 503 answers with Retry-After are waited out, and clean-up steps run last, also after a failure (live environments). A daily rescan finds API changes that break monitored flows. Flows export as Playwright tests or Postman collections when you want them as code (CI and exports).