What is a JSON mock and why it matters
A JSON mock is a simulated response that mimics what a real API would return. The difference between being blocked waiting for the backend to implement an endpoint and being able to push the frontend forward today. Mocks also enable stable automated tests: they don't fail because of timeouts or a flaky database.
List response shape
The most common shape for collections is {"data": [...], "meta": {...}}.
The data array holds items; meta carries pagination, totals and
timestamps. This separation leaves room to grow (HATEOAS links, partial errors) without
breaking existing clients.
Pagination, totals and links
Three fields you'll always want: page, limit and total.
With those, the client knows how many pages remain and can render a paginator. If your API
is cursor-based, return next_cursor instead of a page number.
Errors with a standard shape
The most adopted standard is Problem Details (RFC 7807):
{"type": "...", "title": "...", "status": 422, "detail": "...", "errors": [...]}.
A single error shape simplifies client handling: one parser handles every error response.
Serving the mock
- json-server: spins up a full REST API from a JSON file. Great for prototypes.
- MSW (Mock Service Worker): intercepts fetch in the browser. Ideal for frontend.
- Postman mock servers: hosted, share the URL across the team.
- Vite/webpack dev server: static files in
/public.
Realistic data
Avoid "foo" and "bar". Use plausible names, emails and addresses
(Faker, Mockaroo). The frontend uncovers bugs when strings are long, numbers are negative
or timestamps cross time zones. Flat data hides those edges.
Mock vs contract testing
Mocks can drift from the real API if no one updates them. To prevent it, use contract testing (Pact, OpenAPI schema validation): the mock is validated against the contract and the backend is too. If anyone breaks the contract, tests fail.
Error cases we forget
The most common mock is the happy 200. But the frontend also needs 401, 403, 422 with validation errors, 429 with rate limit, 500 with generic error and 503 with maintenance. Mocks for each case force you to handle them.