Guide · Open source

How to use json-server: a fake REST API from a JSON file

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

json-server is a Node.js tool that turns a JSON file into a working REST API with routes for each top-level key. It is aimed at front-end developers, students and teams who need a backend stand-in while the real API is not ready. After this guide you will be able to install it, start a server from a db.json file, and query the routes with filters, sorting, pagination and relations.

json-servertypicode/json-server · ★ 75.7k · MIT Install options & downloads

Quick start

1Install the package. Run npm install json-server in your project. You need Node.js and npm installed.
2Create db.json. Add a db.json file with top-level keys such as posts, comments and profile.
3Start the server. Run npx json-server db.json. The README says the server starts at http://localhost:3000.
4Request a resource. Use curl http://localhost:3000/posts/1 or open the URL in a browser to check the response.
5Add filters and sorting. Append query parameters such as ?views:gt=100 or ?_sort=-views to narrow and order results.
6Add pagination or embeds. Use ?_page=1&_per_page=25 for pages, or ?_embed=comments to include related data.

What json-server does and who it is for

json-server reads a JSON file (db.json or db.json5) and exposes each top-level key as a REST resource. The README presents it as a development and mocking tool, so it fits local testing, demos and prototypes.

It is a good match for front-end developers who need endpoints before the backend exists, and for students learning how REST routes and query parameters behave. The README does not describe production use, and it does not mention a real database or authentication, so treat it as a stand-in rather than a backend.

Front-end developers building against a backend that is not ready
Demos or prototypes that need data which persists during a session
Students learning REST routes and query parameters
Teams that want a quick mock API for local testing

Install json-server with npm

You need Node.js and npm. The README does not state a required Node.js version, so check the project's documentation if you hit compatibility issues.

Install the package with npm:

npm install json-server

Create a db.json file

Create a file named db.json (or db.json5) in your project. Each top-level key becomes a route. Arrays such as posts and comments become collection resources, while an object such as profile becomes a single object resource.

The README example also includes a $schema line pointing to ./node_modules/json-server/schema.json. You can leave it out if you do not need schema support in your editor.

Array keys (for example posts) get the full set of collection routes
Object keys (for example profile) get GET, PUT and PATCH routes
IDs are strings; json-server generates an ID if you do not provide one

{
  "posts": [
    { "id": "1", "title": "a title", "views": 100 },
    { "id": "2", "title": "another title", "views": 200 }
  ],
  "comments": [
    { "id": "1", "text": "a comment about post 1", "postId": "1" },
    { "id": "2", "text": "another comment about post 1", "postId": "1" }
  ],
  "profile": {
    "name": "typicode"
  }
}

Start the server and make your first request

Run json-server against your file with npx. The README says this starts the server at http://localhost:3000.

Then request a single item with curl. The response is the matching object from your file.

Run json-server --help to see the list of options

npx json-server db.json

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

Use the routes for array and object resources

Array resources accept the standard REST methods: GET for lists and single items, POST to create, PUT and PATCH to update, and DELETE to remove. Object resources accept GET, PUT and PATCH only.

Array: GET /posts, GET /posts/:id, POST /posts, PUT /posts/:id, PATCH /posts/:id, DELETE /posts/:id
Object: GET /profile, PUT /profile, PATCH /profile

Filter, sort, paginate and embed with query parameters

Filters use the form field:operator=value. With no operator, the comparison is equal. The README lists operators including lt, lte, gt, gte, ne, in, contains, startsWith and endsWith. The string operators are case-insensitive.

Sorting uses _sort, with a leading minus for descending order. Pagination uses _page and _per_page; _per_page defaults to 10. Use _embed to include related resources.

Comparison: views:gt=100, title:eq=Hello, id:in=1,2,3
String match: title:contains=hello, title:startsWith=Hello, title:endsWith=world
Sort: _sort=-views or _sort=author.name,-views
Relations: _embed=comments on posts, or _embed=post on comments
Delete dependents: DELETE /posts/1?_dependent=comments

GET /posts?views:gt=100
GET /posts?_sort=-views
GET /posts?_page=1&_per_page=25
GET /posts?_embed=comments

Serve static files

json-server serves files from the ./public directory automatically. To serve other folders, pass them with -s. The README shows that you can pass the flag more than once.

json-server db.json -s ./static
json-server db.json -s ./static -s ./node_modules

Upgrading from v0 or using the v1 beta

The README notes that its v1 documentation is beta and may have breaking changes. If you need the stable v0 behavior, the README links to the v0.17.4 branch. Users upgrading from v0 should check these changes: the id is always a string, _per_page replaces the deprecated _limit, _embed replaces _expand, and the --delay CLI option was removed in favor of browser DevTools network throttling.

ID handling: id is always a string and auto-generated if missing
Pagination: use _per_page with _page instead of _limit
Relationships: use _embed instead of _expand
Request delays: use DevTools throttling instead of --delay

What people use it for

Building a React or Vue front end while the real API is still being written
Demonstrating a prototype with data that persists during a session
Teaching students how GET, POST, PUT, PATCH and DELETE behave on a resource
Testing pagination and filtering logic against predictable data in local development

Frequently asked questions

Is json-server free to use?

json-server is released under the MIT licence, according to the project listing. The README itself does not discuss pricing, so the MIT licence is the relevant point to check.

What do I need to install json-server?

You need Node.js and npm. The README does not specify a Node.js version, so check the project documentation if you run into compatibility problems.

How do I install json-server?

Run npm install json-server in your project folder. To start it without a global install, use npx json-server db.json.

Can I use json-server in production?

The README presents json-server as a development and mocking tool and does not describe production use. Choose a real backend for production systems.

Does json-server support a real database or authentication?

The README does not mention a real database or authentication. Its data comes from a JSON file, so it suits mock data rather than secure, persistent storage.

What are alternatives to json-server?

Projects listed as comparable include JSON Placeholder, Mockoon, MSW (Mock Service Worker) and Mirage JS. Pick one based on whether you need a hosted fake API, a desktop mock tool, or request interception in the browser.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use json-server if you need a quick, file-based REST API for local development, demos or learning how REST queries work. Pick a real backend, or a stable mocking tool for production-like testing, if you need a database, authentication or a long-term supported API.

Install options & downloads