Mock API Server

What is a mock API and why do developers use one?

A mock API is a simulated HTTP server that returns pre-defined responses to HTTP requests without executing real business logic or touching a database. Instead of pointing your frontend at a live backend, you point it at the mock, which replies with whatever JSON you configure. From the perspective of your JavaScript code, the response is indistinguishable from a real one — it arrives over the same fetch call, carries the same HTTP status code, and contains the same JSON structure.

The most common reason to use a mock API is parallel development. In a typical product team, the backend engineers and frontend engineers agree on a contract — the shape of the request and the shape of the response — and then split off to build their respective sides simultaneously. Without a mock, the frontend team is blocked until the backend endpoints are ready and deployed to a shared environment. A mock API eliminates that dependency entirely. Frontend engineers can build, wire up, and iterate on their UI without waiting for a single line of backend code to exist.

The second major use case is testing edge casesthat are difficult or impossible to reproduce against a real backend. What happens in your UI when the server returns a 500 error? What does your loading skeleton look like when the API takes three seconds to respond? What does the empty-state component render when the API returns an empty array? With a real backend you'd need to engineer special conditions to trigger each of these scenarios. With a mock, you define them declaratively and switch between them instantly.

A third use case is demos and prototypes. If you want to show a stakeholder or client how a feature will look before any backend infrastructure exists, a mock API lets you wire up a fully interactive prototype in hours rather than days. The demo experience is indistinguishable from a real integration.

Finally, mock APIs are valuable for reliable test data. Real APIs are stateful — running a test suite against a live database can leave behind side effects that cause subsequent runs to fail. A mock always returns exactly what you configured, making your test suite deterministic and reproducible regardless of the order in which tests run.

How browser-based mocking works

Traditional mock servers require running a Node process (json-server, Express, etc.) on your machine. This tool uses a Service Worker to intercept fetch requests from the same browser tab. When your code calls fetch('/api/users'), the Service Worker matches it against your configured routes and returns the response — no actual network request happens.

Service Workers are a browser-native technology that sit between your web page and the network. Originally designed for offline Progressive Web Apps, they can intercept any outgoing fetch request and respond to it programmatically. This means the mock runs entirely inside your browser — there is no server process, no port to configure, and no firewall rules to worry about. The Service Worker code is sandboxed to its origin and cannot affect other tabs or other websites.

When a route does not match any configured mock, the request is passed through to the real network. This is important: it means you can mock only the endpoints you care about and let everything else — your CDN assets, analytics, third-party scripts — continue to work normally.

Defining mock routes

Each mock route has five fields: method, path, status code, response body (JSON), and optional delay. You can add as many routes as you need.

The method field accepts any standard HTTP verb — GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS. The path supports static segments such as /api/users and parameterised segments such as /api/users/:id. When using a parameterised segment, the mock will match any request that fits the pattern regardless of what the actual :id value is — useful for simulating both a successful look-up and a not-found case on the same endpoint type.

The response body is a JSON editor. You type (or paste) the exact JSON object or array you want the mock to return. The editor validates the JSON on every keystroke and highlights syntax errors before you save. Here is an example response body for a user list endpoint:

{
  "data": [
    { "id": 1, "name": "Alice Chen", "role": "admin", "active": true },
    { "id": 2, "name": "Bob Patel", "role": "editor", "active": true },
    { "id": 3, "name": "Carol Kim",  "role": "viewer", "active": false }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "per_page": 20
  }
}

Notice the meta wrapper — it reflects the envelope structure many real APIs use for paginated responses. By matching your mock data to the shape your real API will eventually return, you ensure that all the frontend code you write against the mock will work without changes once the real backend is ready.

Simulating status codes

One of the most powerful aspects of a mock API is the ability to return any HTTP status code on demand. Real backends rarely produce certain error codes in a way that's easy to trigger repeatedly during development — a 503 Service Unavailable, for example, would require the real server to be degraded. With a mock you can pin a route to any status code and test your UI's response in seconds.

The commonly useful status codes and what to test with each:

A particularly useful pattern is defining two routes with the same method and path — one returning 200 and one returning 500 — and toggling between them. This lets you quickly flip a route between the happy path and the error state without re-editing the JSON body each time.

Simulating real-world conditions: latency and delays

A mock that responds instantly every time is not realistic. Real networks have variable latency — a mobile user on a congested 4G network might experience 400-800ms of round-trip time for a simple API call. If you develop entirely against instant responses, you may ship a UI that has no loading states, freezes during slow fetches, or shows jarring content jumps when data loads too quickly for the eye to track.

The delay field on each route solves this. Set it to any value in milliseconds and the Service Worker will wait that long before returning the response. Common useful delay values:

Delays are set per-route, so you can mix fast and slow responses in the same session — for example, a fast user profile load combined with a slow analytics summary that simulates an expensive aggregation query. This allows you to build and test skeleton loaders that appear independently as each piece of data arrives.

Typical development workflows

Understanding when to bring in a mock API — and how to structure your work around it — makes a bigger difference than any individual feature. Here are the patterns that work best in practice.

Building realistic mock responses

The quality of your mock data directly affects how useful the mock is. Minimal placeholder data — single-character strings, sequential IDs, all-zero timestamps — makes it harder to spot layout bugs in your UI and gives an unrealistic picture during demos. Invest a few extra minutes in crafting realistic JSON.

Here are a few patterns worth following:

For error responses, include a body that matches what the real API will return. Many APIs wrap errors in a standard envelope — for example:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The email address is already in use.",
    "fields": {
      "email": ["Email has already been taken"]
    }
  }
}

Pairing the mock server with the API client

The mock API server and the API client tool complement each other naturally. Use the API client to send a request to your mock route and inspect the exact JSON body, headers, and status code it returns. This makes it easy to spot typos in your JSON or misconfigured status codes before you wire them up in your frontend application code.

A common workflow is to open the mock server in one browser tab, define your routes, then switch to the API client tab and fire requests at the same mock origin to verify responses. Because both tools run in the same browser and the Service Worker is scoped to the origin, requests from the API client are intercepted by the mock exactly as they would be from your application code.

Frequently Asked Questions