SpunkArt
Websites, APIs and search

What a mock API server is and how to run one locally

A mock API server answers requests with canned responses instead of real data. It lets you build and test a front end before the real back end exists, or without touching production.

Why fake an API at all?

Front-end work often starts before the server is ready. If the screen that lists orders has to wait for the orders endpoint, the whole team waits. A mock server breaks that dependency. You agree on the shape of the response first, write it down as sample JSON, and serve that sample from your own machine.

Mocks also help when the real service is slow, rate-limited, costs money per call, or returns data you cannot control. You can force the awkward cases on demand: an empty list, a very long name, a 500 error, a response that takes eight seconds.

The three levels of mocking

LevelWhat it isGood for
Static fileA .json file served from a folderRead-only screens, quick prototypes
Small scriptA few lines of server code that pick a response by path and methodSeveral endpoints, status codes, delays
Contract-drivenResponses generated from an API description such as an OpenAPI fileTeams that already maintain a spec

Level one: a folder of JSON

Create a folder named mock and inside it a file users.json:

[
  {"id": 1, "name": "Ada", "role": "admin"},
  {"id": 2, "name": "Lin", "role": "editor"}
]

From the parent folder run python3 -m http.server 8000. Your code can now request localhost:8000/mock/users.json. This handles GET only, and every request gets the same answer, but for many early screens that is enough.

Level two: a tiny router

When you need POST, custom status codes or delays, write a short script in whatever language your team already uses. The logic is always the same three steps:

  1. Read the method and the path of the incoming request.
  2. Look them up in a table of canned responses, for example GET /orders or POST /orders.
  3. Send back the stored status code, a Content-Type: application/json header and the stored body. Add an optional pause to imitate a slow network.

Keep the table in one file so anyone can add a case without reading the server code.

Designing good fake data

  • Copy the real shape exactly. Same field names, same nesting, same types. A mock that returns "id": "1" when production returns "id": 1 hides bugs.
  • Include edge cases on purpose. A null avatar, an empty array, a 300-character title, accented characters.
  • Use invented values only. Never paste real customer records into a mock; mocks end up in repositories and screenshots.
  • Mock errors as well as success. A 401, a 404 and a 422 with a validation message are worth a file each.

Where mocks go wrong

The main risk is drift. The real API changes, the mock does not, and the front end passes every local test then fails against the live service. Two habits reduce this: generate mocks from the same spec the back end uses, and run at least one test suite against the real staging service before a release. Also watch for CORS: a browser page on one port calling a mock on another port needs the mock to send an Access-Control-Allow-Origin header.

Questions

Is a mock the same as a stub?

People use the words loosely. In testing, a stub usually returns fixed answers inside one test, while a mock server is a separate process your app talks to over the network.

Can I mock a third-party API?

Yes. Record one real response, remove any secrets or personal data, and serve the cleaned copy. Recheck it when the provider publishes a new API version.