How to Create a Mock REST API with JSON Server

JSON Server lets you test a frontend against a local REST API before the backend is ready. You define sample data in a JSON file, start the server, and send requests to read or change it. Use disposable test data: the mock has no production authentication or database guarantees.

The examples below use 1.0.0-beta.15. This is a beta release, so upgrades may change behavior. The guide also identifies differences from 0.17.4 for projects that depend on that older release. Install the version your project expects and keep its lockfile.

Choose the release line before installing

Consult the upstream documentation, v0.17.4 documentation, and npm package metadata when choosing a version. The runtime minimum in the table is a package requirement; use a supported Node.js release for your environment.

For relationships in beta.15, use _embed in both directions. Older examples may use _expand; the migration notes replace it with _embed. The discussion in issue #1638 provides background on that change.

Prerequisites and a project-local install

Check Node.js and npm first:

node --version
npm --version

For a new v1 prototype, create a dedicated project and pin the example release:

mkdir json-server-demo
cd json-server-demo
npm init -y
npm install --save-dev --save-exact json-server@1.0.0-beta.15
npx json-server --version

The v1 package requires Node.js 22.12.0 or newer. If the installed runtime is older, update Node.js through a supported operating-system or Node.js distribution method before installing the package.

For an existing legacy fixture that depends on v0 behavior, pin it explicitly in that project:

npm install --save-dev --save-exact json-server@0.17.4
npx json-server --version

Do not install both release lines into one project and assume commands are interchangeable. Keep separate fixtures or branches and test the migration.

Create a v1 mock database

Add db.json with string IDs and a relationship field:

{
  "posts": [
    { "id": "1", "title": "First post", "views": 150 },
    { "id": "2", "title": "Second post", "views": 50 }
  ],
  "comments": [
    { "id": "1", "text": "Useful example", "postId": "1" }
  ],
  "profile": {
    "name": "Demo team"
  }
}

Start the pinned project-local binary:

npx json-server db.json

The beta.15 CLI watches the data file automatically and listens on localhost:3000 by default. Available options include --port, --host, and repeatable --static; run npx json-server --help against the installed version before adding another flag.

Verify CRUD behavior

Read the collection and one record:

curl --fail http://localhost:3000/posts
curl --fail http://localhost:3000/posts/1

These commands create a new record, change the views on post 1, and delete post 2. Run them against the disposable example database:

curl --fail -X POST http://localhost:3000/posts \
  -H 'Content-Type: application/json' \
  -d '{"title":"Temporary post","views":0}'

curl --fail -X PATCH http://localhost:3000/posts/1 \
  -H 'Content-Type: application/json' \
  -d '{"views":151}'

curl --fail -X DELETE http://localhost:3000/posts/2

JSON Server writes mutations back to the data file. Keep a clean fixture in version control or regenerate it before each repeatable test.

Filter, sort and paginate with v1

Conditions

The beta.15 query syntax uses field:operator=value. Available operators include lt, lte, gt, gte, eq, ne, in, contains, startsWith, and endsWith.

curl --fail 'http://localhost:3000/posts?views:gte=100'
curl --fail 'http://localhost:3000/posts?title:contains=post'

Legacy expressions such as views_gte=100 belong to v0.17.4 and should not be copied into a v1 test.

Sorting

Use a minus prefix for descending order and commas for multiple fields:

curl --fail 'http://localhost:3000/posts?_sort=-views'
curl --fail 'http://localhost:3000/posts?_sort=title,-views'

Pagination

Use _page with _per_page:

curl --fail 'http://localhost:3000/posts?_page=1&_per_page=10'

The v1 response is an object containing navigation fields and a data array. A client written for the v0 array response must be updated before migrating.

Relationships

Fetch comments with their post, or posts with their comments:

curl --fail 'http://localhost:3000/posts?_embed=comments'
curl --fail 'http://localhost:3000/comments?_embed=post'

Do not use _expand in a v1 example. Use _embed for the relationship queries shown above.

Complex conditions

Beta.15 also supports _where with a JSON object. URL-encode it in application code rather than assembling unescaped JSON into a user-controlled URL.

Keep legacy-only features with the legacy release

JSON Server 0.17.4 documents route mappings, CLI middleware, and a CommonJS module interface. Beta.15 does not expose --routes or --middlewares in its CLI and its package declares an ES module.

If an existing mock depends on a route map, keep it pinned to v0.17.4 while you design and test a replacement:

{
  "/api/*": "/$1"
}

npx json-server@0.17.4 --watch db.json --routes routes.json

A v0 CommonJS middleware example will not work unchanged in v1. Use a separate, maintained application or reverse proxy when a v1 prototype needs authentication, validation, custom routing, or other server behavior.

Serve static development files

JSON Server automatically serves an existing public directory. The beta.15 CLI can add another static directory with --static or -s:

npx json-server db.json --static ./static

Verify that API routes and static paths do not collide.

Share the mock API without making it public

The default localhost listener is the safest development choice. A remote team environment needs an explicit access design because JSON Server has no production authentication or authorization layer.

Before changing the host binding:

1. Restrict the network path to a VPN, private network, or exact source addresses.
2. Put HTTPS and authentication in a separate maintained gateway when traffic leaves a trusted host.
3. Keep the JSON fixture free of real customer data, credentials, tokens, and secrets.
4. Back up or regenerate the fixture before tests that write data.
5. Confirm the service is not reachable from an unintended public address.

For a self-managed VPS, the customer owns installation, firewall and proxy configuration, TLS, authentication, updates, monitoring, fixture recovery, and removal of the temporary service.

Update or roll back the project

Keep the exact version in package.json and commit the lockfile. Before updating:

npm ls json-server
npx json-server --version

Run regression tests for every CRUD operation, condition, sort, pagination response shape, relationship, and static path the frontend uses. If the update changes behavior, restore package.json and the lockfile, reinstall, and restore the clean JSON fixture.

Do not move a legacy project from 0.17.4 to v1 by changing only the version number. String IDs, condition syntax, sorting, pagination response shape, relationships, CLI flags, and module integration all require review.

Troubleshooting

The package refuses the Node.js version

Run node --version and npm view json-server@1.0.0-beta.15 engines. Beta.15 requires Node.js 22.12.0 or newer.

A copied flag is unknown

Run npx json-server --help in the project. --routes, --middlewares, and --watch appear in legacy documentation but not in the beta.15 CLI help.

A filter returns the wrong records

Confirm the release. Use views:gte=100 with beta.15, but views_gte=100 with v0.17.4.

Pagination breaks the frontend

Beta.15 returns a pagination object with records under data; v0 returns an array. Update the client contract or remain on the pinned legacy release.

Relationship results are empty

Use string IDs and matching foreign keys in v1, then use _embed as documented. Do not use the removed _expand form.

When JSON Server is the wrong tool

Choose a purpose-built mock or test server when you need deterministic failure simulation, request matching, latency controls, contract validation, authentication, or complex state. Use a real application and database for production data, durability, access control, audit requirements, concurrent writes, migrations, and operational recovery.

JSON Server is most valuable when its scope stays small: a pinned, disposable API that lets frontend work proceed while the real backend contract is still being built.