API Mocking: A Complete Guide
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.
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.
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 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 | What a generator can read out of a schema, and what it cannot |
| Which rule answers | Method, path, query and header matching, and priority as a tiebreak |
| Mock data worth testing against | Static, generated and fixture data, and what each one hides |
| One endpoint, many answers | Conditional responses instead of a rule per case |
| Errors, latency and rate limits | Making the mock unpleasant on purpose, and why that is the point |
| Stateful mocks | When a mock needs memory, and when memory makes it a bad backend |
| Keeping mocks in sync | Following a draft, pinning a version, and what regeneration overwrites |
| Mocks in frontend work | CORS, tokens, base URLs, and the switch to the real backend |
| When not to mock | Where a mock proves nothing, and what takes over there |
| What to look for in a tool | 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, and the data a mock serves is the same data your tests use, which 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.
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 guide in the product documentation, or read on. The API mocking feature page 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.
Last reviewed by The Routebase Team.