# API Mocking: A Complete Guide — Routebase

> What API mocking is, how a mock server is generated from an OpenAPI contract, how to give it realistic data, errors, latency and state, and where a mock stops being evidence.

Canonical page: https://routebase.dev/guides/api-mocking/
Guide overview · 10 chapters · Last reviewed 2026-09-13 · The Routebase Team

A mock server answers. That is the whole trick, and it is also where the trouble starts, because something that answers is easy to mistake for something that works.

This guide covers what a mock is for and how one is derived from a contract instead of written by hand. It also covers how to make it behave enough like the network it replaces that the client survives the real thing. It also covers the sentence most articles on the subject leave out, which is where a mock stops being evidence.

## What a mock is actually for

Three jobs come up over and over, and they are worth separating because each one wants a different mock.

**Unblocking a consumer.** The frontend, the mobile app or the neighbouring service needs something at a URL today, and the provider ships in six weeks. This is the job the word usually refers to, and it is the one that tolerates the least fidelity.

**Making rare conditions ordinary.** Production produces a `429`, a timeout and an empty list eventually and at inconvenient moments. A mock produces them on demand, which is the only practical way to build the handling for them.

**Arguing about a shape while it is cheap.** A request against a mock is the fastest way to find out that a field is missing or nested one level too deep. Finding that out from a running mock costs an edit, while finding it out after release costs a version.

_Figure: The same request answered by a mock and by the real service. The mock can be right about the shape and about the conditions, because both are configured. It cannot be right about the behaviour, because there is no behaviour behind it, and that is the one column that decides whether the feature works._

## The family it belongs to

Several things get called mocks, and the words matter here because they set expectations about what a green result means.

| Name | What it does | What it is good for |
|---|---|---|
| Stub | Returns a fixed answer for a given call | Getting a consumer past a dependency |
| Mock | A stub that also records how it was called | Asserting that something was invoked |
| Fake | A real implementation with a shortcut inside | Exercising logic without the infrastructure |
| Sandbox | The provider's own deployment with test data | Checking the provider's behaviour, not just its shape |
| Record and replay | Captured real traffic, played back | Reproducing something that already happened |
| Service virtualisation | A modelled stand-in for a whole system | Load and integration work across many dependencies |

A mock server sits between the first two and the fifth. Tools in the category include WireMock, Prism, Mockoon and Beeceptor, and they differ mostly in where the response comes from and in how much behaviour you can configure on top of it.

## Where the body comes from decides the rest

Every property that makes a mock useful or dangerous follows from one question, which is what produced the response body.

A body typed by hand is a second opinion about the API. It starts correct and then diverges, because it lives in a repository the provider team does not read and gets edited by whoever needs a field this afternoon. Nothing announces the moment it starts disagreeing with the contract.

A body derived from the contract cannot disagree while it is still derived. That is a real property with an exact edge, because the moment somebody edits the body by hand the derivation stops and the rule belongs to them. [Keeping mocks in sync](/guides/api-mocking/keeping-mocks-in-sync/) is the chapter on where that edge sits.

## The short answer

If you take one rule from this guide, take this one. Derive the mock from the contract, and then configure it to behave worse than you expect production to behave.

The rest of the guide is that rule taken apart.

| Chapter | Answers |
|---|---|
| [Mocking an API from OpenAPI](/guides/api-mocking/mock-api-from-openapi/) | What a generator can read out of a schema, and what it cannot |
| [Which rule answers](/guides/api-mocking/mock-request-matching/) | Method, path, query and header matching, and priority as a tiebreak |
| [Mock data worth testing against](/guides/api-mocking/mock-data-generation/) | Static, generated and fixture data, and what each one hides |
| [One endpoint, many answers](/guides/api-mocking/conditional-mock-responses/) | Conditional responses instead of a rule per case |
| [Errors, latency and rate limits](/guides/api-mocking/simulating-errors-latency-and-rate-limits/) | Making the mock unpleasant on purpose, and why that is the point |
| [Stateful mocks](/guides/api-mocking/stateful-mocks/) | When a mock needs memory, and when memory makes it a bad backend |
| [Keeping mocks in sync](/guides/api-mocking/keeping-mocks-in-sync/) | Following a draft, pinning a version, and what regeneration overwrites |
| [Mocks in frontend work](/guides/api-mocking/mocking-for-frontend-development/) | CORS, tokens, base URLs, and the switch to the real backend |
| [When not to mock](/guides/api-mocking/when-not-to-mock/) | Where a mock proves nothing, and what takes over there |
| [What to look for in a tool](/guides/api-mocking/api-mocking-tools/) | Criteria as questions rather than a list of vendors |

Two neighbouring subjects live elsewhere. The document the mock is generated from is covered in the [OpenAPI guide](/guides/openapi/), and the data a mock serves is the same data your tests use, which [test data](/guides/api-testing/api-test-data/) covers in full.

## In Routebase

Every project gets one mock server with its own public base URL, and it is either answering or switched off without losing a line of configuration.

_Screenshot: The rules, the base URL, the coverage against the specification and the live request log sit in one window, so what the mock answered and why it answered that way are never two tools apart._

Rules can be generated from a specification in one step, and the response bodies come from the schemas rather than from a text editor. On top of that sit the parts that make a mock resemble the network, which are conditional responses, simulated errors, latency, rate limits and state. Start with the [Mock Server](https://docs.routebase.dev/mock-server/) guide in the product documentation, or read on. The [API mocking feature page](/api-mocking/) has the short version of how mocking fits into the rest of the lifecycle.

## Frequently asked questions

### What is API mocking?

API mocking is standing up something that answers HTTP requests the way a real API would, before that API exists or while it is unavailable. A mock has the routes, the status codes and the response shapes of the real thing, and none of its logic. The point is that a consumer can be built, demonstrated and tested against the interface while the implementation behind it is still being written.

### How do you mock an API from an OpenAPI specification?

You read the paths and generate one rule per operation, then build each response body from the response schema of the status code you want. A field typed as a string with a date-time format produces a timestamp, and a field named email produces something shaped like an address. Everything the document leaves untyped comes back empty, which makes a generated mock an unusually honest report on the quality of your schemas.

### What is the difference between a mock, a stub and a fake?

A stub returns a canned answer and has no opinion about who called it. A mock is a stub that also records the calls, so a test can assert that something was invoked in a particular way. A fake is a working implementation with a shortcut inside it, such as an in-memory store standing in for a database. In everyday API work the word mock has absorbed all three, and a mock server is usually a stub with configuration.

### Can you test an API against a mock server?

You can test a consumer against a mock server, and that is what one is for. You cannot test the provider that way, because a passing run against a mock is a statement about the mock and about nothing else. The moment you want evidence that the real service behaves, you need requests that reach the real service, which is what contract tests in a pipeline and monitors against a live environment are for.

## Chapters in this guide

1. [Mocking an API from an OpenAPI Contract](https://routebase.dev/guides/api-mocking/mock-api-from-openapi/): Why mocks are derived rather than written, what a generator can read out of paths, status codes and schemas, what it cannot know, and why coverage is the measure that matters.
2. [Which Rule Answers a Mock Request](https://routebase.dev/guides/api-mocking/mock-request-matching/): A mock server is a router before it is anything else. What can be matched, why several rules routinely overlap, how priority breaks the tie, and what should happen when nothing matches.
3. [Mock Data Worth Testing Against](https://routebase.dev/guides/api-mocking/mock-data-generation/): Static, generated and fixture data as three sources with three different failure modes, why a field filled with the word string ruins every layout, and how locale and time format quietly break a client.
4. [One Endpoint, Many Answers](https://routebase.dev/guides/api-mocking/conditional-mock-responses/): How to get a valid case, a not-found and a validation failure out of one route without a rule per outcome, what to branch on, and which fallback belongs at the end.
5. [Making the Mock Unpleasant on Purpose](https://routebase.dev/guides/api-mocking/simulating-errors-latency-and-rate-limits/): Latency with a range, failures at a probability, a dead socket rather than a clean 500, and the 429 nobody handles. The four conditions a client only meets in production unless the mock produces them.
6. [Stateful Mocks: When the Attempt Needs Memory](https://routebase.dev/guides/api-mocking/stateful-mocks/): Why a create followed by a list is the flow every stateless mock fails, what state buys you in a cart or a wizard, and where memory turns a mock into a bad backend.
7. [Keeping Mocks in Sync With the Spec](https://routebase.dev/guides/api-mocking/keeping-mocks-in-sync/): A mock behind the contract is worse than no mock. The three states a generated rule can be in, why a published version should freeze rather than follow, and what regeneration overwrites.
8. [Mocks in the Frontend Workflow](https://routebase.dev/guides/api-mocking/mocking-for-frontend-development/): Starting on day one instead of waiting, the base URL as configuration rather than a code branch, CORS and tokens in a browser, and what changes on the day you switch to the real backend.
9. [When Not to Mock](https://routebase.dev/guides/api-mocking/when-not-to-mock/): A passing run against a mock is a statement about the mock. The four questions mocking cannot answer, what takes over in each of them, and proxy mode as the path between a stand-in and the real service.
10. [What to Look For in an API Mocking Tool](https://routebase.dev/guides/api-mocking/api-mocking-tools/): Eight criteria that decide whether a mock is still trusted in three months, written as questions to ask rather than as a list of vendors, plus two exercises that settle it faster.

---

[Routebase](https://routebase.dev/) — [Sign up](https://app.routebase.dev/): Every account starts with a 14-day Pro trial — no credit card required.