JSON-Server Installation: Setting Up Mock APIs

JSON Server turns a JSON file into a disposable REST API for frontend development, tests, workshops, and demonstrations. It is useful when the real backend is unavailable, but it is not a production database or an authenticated public API.

Last checked: 11 August 2026.

The current upstream README describes v1 as beta software that is usable but may introduce breaking changes. npm's latest tag and the newest GitHub release both point to 1.0.0-beta.15; the separate legacy line remains 0.17.4. Pin the line your project expects instead of relying on an unqualified install.

Choose the release line before installing

Sources: current upstream README, v0.17.4 README, and npm package metadata, checked 11 August 2026.

Issue #1638, previously cited as unresolved, closed as completed on 29 January 2026. Current v1 documentation uses _embed for both relationship directions and lists _expand as a v0-to-v1 migration change. The current guide therefore uses _embed and does not retain the obsolete unresolved-issue workaround.

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 checked release:

mkdir json-server-demo
cd json-server-demo
npm init -y
npm install --save-dev 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 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 current CLI watches the data file automatically and listens on localhost:3000 by default. Its verified options are --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 /posts
curl --fail /posts/1

Create, update, and delete a disposable record:

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

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

curl --fail -X DELETE /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.

Use the current v1 query syntax

Conditions

The current v1 README uses field:operator=value. Available operators include lt, lte, gt, gte, eq, ne, in, contains, startsWith, and endsWith.

curl --fail '/posts?views:gte=100'
curl --fail '/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 '/posts?_sort=-views'
curl --fail '/posts?_sort=title,-views'

Pagination

Use _page with _per_page:

curl --fail '/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

Use _embed in the direction documented by the current README:

curl --fail '/posts?_embed=comments'
curl --fail '/comments?_embed=post'

Do not use _expand in a v1 example. The current migration notes explicitly replace it with _embed.

Complex conditions

The current README also documents _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. The current v1 CLI help does not expose --routes or --middlewares, and current v1 package metadata 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

Do not present a v0 CommonJS middleware example as a v1 workaround. 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 current v1 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 and rollback

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. The checked v1 release 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 current v1 CLI help.

A filter returns the wrong records

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

Pagination breaks the frontend

Current v1 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.