Field guide / API mocking
Design API mocks that reveal integration problems instead of hiding them
A practical approach to choosing endpoints, examples, errors, state, latency, and ownership for mocks that teams can trust.
1Consumer journey
2Representative payload
3Failure states
4Named owner
Fidelity follows consumer risk—not payload size.
Working reference
What goes in, what comes out, and what the result can prove.
Concrete artifact
Design a behavior matrix before writing fixtures
Scenario Status Delay State transition
happy path 200 80ms none
not found 404 40ms none
rate limited 429 20ms retry after 30s
accepted 202 120ms pending → completeReview sequence
Three checks before the result becomes a decision.
Contract fidelity
Use realistic status, headers and payload shape.
Failure coverage
Include validation, auth, rate-limit and upstream failures.
State
Model transitions only when the client depends on them.
Limits
What this workflow does not prove.
- Mocks validate the client’s assumptions, not the provider implementation.
- Overly permissive matching can hide malformed requests.
- Pair mocks with contract and controlled integration tests.
Questions worth answering
Before you put it into a real workflow.
Should every endpoint be mocked?
No. Start with the consumer journeys that are blocked or carry the highest integration risk.
Where should examples come from?
Prefer contract examples and sanitized representative payloads over arbitrary generated shapes.
How do mocks become stale?
They drift when the source contract or real behavior changes without an owner updating the scenarios.
Next move
Start with one concrete API problem.
Keep the first step small. Move into a workspace when the result deserves to be saved, repeated, or shared.