The API Mocking Guide: Servers, Tools, and When to Use
Quick answer: API mocking stands in for a real service with a controllable stand-in that returns canned or spec-driven responses, so frontend, mobile, and integration work can proceed before the backend is ready — and so you can test edge cases (timeouts, 500s, empty states) that are hard to produce against a live system. The durable approach is to generate mocks from the same OpenAPI contract you test against, so the mock cannot drift into describing an API that no longer exists.
This guide covers when to mock, the two main places a mock can live (network vs server), how the leading tools differ, and the one mocking mistake that makes tests worthless. Follow the links for the concrete setups.
All articles in this guide
Each article below is a focused, pain-point-driven read that belongs to this hub. New ones are added on a regular schedule; the ones still in progress are marked.
The Agent Mocks the Very Function Under Test
The test replaces the thing it is supposed to verify, so it cannot fail. Spotting the self-mocking test.
Read the article →Tests That Mock the Function Under Test, Written Out
The same mistake written out line by line, with the corrected test beside it.
Read the article →Mocking an API for the Frontend: MSW vs Prism
Two common ways to keep frontend work moving, and where each one fits the stack.
Read the article →The Best OpenAPI Mock Servers for 2026
The spec-driven mock options worth using now, with the real limits of each.
Read the article →OpenAPI Examples as a Single Source of Truth
Examples duplicated in docs, mocks, and tests drift. Keeping them defined once, in the spec.
Read the article →429 and Retry-After: Mocking Rate Limits Honestly
How to model rate limits so clients and mocks behave correctly under load.
Read the article →207 Multi-Status for Partial Batch Failure
Returning per-item results for a batch instead of one all-or-nothing status.
Read the article →RFC 9457: A Standard Shape for Error Responses
A standard, machine-readable error shape that clients and agents can rely on.
Read the article →Mocking Idempotency: Replaying the Same Key Should Return the Same Result
Model idempotency-key state in the mock so a retry returns the stored result instead of creating a duplicate.
Read the article →Mocking Outbound Webhooks: Signing Payloads and Retrying Delivery
Verify signatures and model failures in a local receiver to test webhook delivery deterministically.
Read the article →Mocking Pagination Without Letting Test Data Leak Between Pages
How to build a cursor-aware mock over seeded data so pages advance without overlap and terminate cleanly.
Read the article →Mocking Conditional Requests: ETags and 304 Not Modified
How a stateful mock reproduces the ETag and 304 lifecycle to test client revalidation.
Read the article →Mocking SSE: Streaming Events and How a Client Handles a Dropped Connection
How a time-aware SSE mock verifies framing, reconnect, and resume instead of returning a static event list.
Read the article →Mocking Timeouts: When a Stub Never Returns and the Client Retries
How to stub a server that never responds so the client timeout, backoff, and idempotency path actually gets tested.
Read the article →Mocking File Uploads: Returning 413 for an Oversized Payload and 201 on Success
Building an upload mock that branches into 413 over the limit and 201 under it, instead of one canned success.
Read the article →Mocking a Circuit Breaker: 503 While Open, Then a Half-Open Recovery
A stateful mock for the closed, open, and half-open circuit breaker transitions.
Read the article →Mocking a 410 Gone for a Retired Resource vs a Plain 404
Why a retired resource should return 410, not 404, and how to mock the permanent response.
Read the article →When to mock and when not to
Mock to unblock parallel work, to reproduce rare failures, and to keep a test suite fast and independent of third-party uptime. Do not use a mock to avoid testing the real integration — the point where a mock and the live service diverge is exactly where production bugs hide. The end-to-end flow that starts from a contract and produces mocks alongside tests is in from a scanned spec to mocks, scenario tests, and an MCP server.
Spec-driven mock servers
A mock server reads an OpenAPI document and serves responses that match it, including the example payloads and status codes you declare. This is the most maintainable kind of mock because the contract enforces the shape. The leading options and how they compare are surveyed in the best OpenAPI mock servers for 2026. To make the generated responses realistic, the format and constraint keywords have to be modeled correctly; see JSON Schema formats, constraints, codegen, and mocks, and keep the examples authoritative with examples as a single source of truth.
Network-level mocks: MSW vs Prism
There are two common homes for a mock during development. A server-side mock (like Prism) runs as a process you point the app at, and a network-level mock (like MSW) intercepts requests inside the browser or test runtime. The choice shapes your whole workflow; the tradeoffs and a recommendation are in mocking an API for the frontend: MSW vs Prism. MSW is especially valuable for component tests because it lets you exercise the real fetch path without a live server; Prism is better when you want a standalone process shared by multiple clients.
Mocking the cases the real API won't give you
The strongest reason to mock is deterministic control over failure. Use the mock to serve slow responses, 500s, malformed bodies, and empty or paginated lists so the UI's error and loading states actually get exercised. These states map to the reliability patterns the contract should describe: 429 and Retry-After, 207 Multi-Status for partial batch failure, and RFC 9457 error shapes.
The mocking trap: mocking the thing you're testing
One mistake empties a test of all value: replacing the unit under test with a mock, so the test only asserts that the mock returns what you told it to. The failure is documented in an agent mocks the function under test and tests that mock the function under test. The rule is to mock at the boundary — the collaborators your code calls over the network — and leave the code being tested real.
Where to go next
Powerduck is the local-first, OpenAPI-first workspace that carries this whole flow — from the contract through debug, test, mock, and the tools an agent can call. See it on the Powerduck homepage.
Mocking is one layer of verification. Pair it with the assertions in the API testing guide, and when a real call fails, use the API debugging guide. If you are choosing a tool that can both mock and debug against the spec, the Postman alternatives page compares the integrated options.
Frequently asked questions
What is the difference between a mock, a stub, and a fake?
A stub returns canned answers to specific calls; a fake is a working but simplified implementation (an in-memory database); a mock is a stub that also verifies the interactions made against it. In practice, "API mock" is used loosely for all three, but the distinctions matter when you assert call behavior.
Should mocks be used in production?
No. Mocks are for development and tests. A production fallback should be a deliberate degraded-mode response, clearly labeled, not a mock that could mask a real outage.
How do I stop mocks drifting from the real API?
Generate them from the OpenAPI contract, validate responses against the schema in CI, and keep one set of examples shared by both mocks and tests.