JSON-Server: Fake REST API from a JSON File
/json-server
JSON-Server turns a single JSON file into a full REST API with GET, POST, PUT, PATCH, and DELETE routes, no backend code required. You add filtering, sorting, pagination, and relationship embedding through query params instead of writing controllers. Reach for it when you need a fake API to build or test against before the real backend exists; skip it if you need auth, business logic, or a production data layer.
What is JSON-Server?
JSON-Server is a Node.js tool that reads a db.json file, or its db.json5 variant, and serves its top-level keys as REST resources, so a posts array becomes GET/POST/PUT/PATCH/DELETE routes at /posts. Run it with npx json-server db.json and it starts an HTTP server on port 3000, backed by whatever data sits in that file. Query params handle filtering, sorting, and pagination without extra setup.
Key Features for Mock APIs
- โFull CRUD routes for array resources: GET, POST, PUT, PATCH, and DELETE on /posts, generated straight from the JSON file's structure.
- โQuery-based filtering with explicit operators โ field:operator=value โ covering eq, ne, lt, lte, gt, gte, in, contains, startsWith, and endsWith.
- โSorting via _sort, including descending order with a minus prefix and multi-field sorts like _sort=author.name,-views.
- โPagination through _page and _per_page, which defaults to 10 per page and returns first/prev/next/last/pages/items metadata alongside the data.
- โRelationship embedding with _embed, so GET /posts?_embed=comments attaches each post's comments inline.
- โComplex boolean queries via _where, which accepts a raw JSON filter object and overrides the simpler query params when present.
- โAutomatic static file serving from ./public, plus additional directories with the -s flag.
- โCascading deletes with _dependent, so DELETE /posts/1?_dependent=comments removes a post's comments along with it.
When to Use JSON-Server
- โขBuilding a frontend against realistic REST endpoints before the actual backend team has shipped anything.
- โขWriting integration tests that need real HTTP requests and responses instead of mocked fetch calls.
- โขPrototyping a data model quickly by editing db.json directly and watching routes update.
- โขDemoing an app with static files served alongside API data, using the built-in ./public directory support.
Getting Started: Installation
Install json-server as a project dependency with `npm install json-server`. There's no global-install instruction in the README; the usage example runs it straight through npx (`npx json-server db.json`), which works whether or not it's installed locally. Run `json-server --help` for the full list of CLI options โ the README doesn't enumerate every flag inline, so that command is the actual reference for flags like -s for static directories.
Creating and Accessing a Fake API
Create a db.json file with top-level arrays and objects โ for example a posts array with id/title/views fields, plus a comments array referencing postId. JSON5 is also supported (db.json5), which allows comments and trailing commas in the file. Start the server with `npx json-server db.json`; it listens on http://localhost:3000 and logs that address on startup. From there, `curl http://localhost:3000/posts/1` returns the matching post as JSON, and the same array becomes full CRUD routes at /posts. Query params layer on top of those routes for filtering, sorting, pagination, embedding, and complex _where filters.
Strengths
- โFull CRUD generated from the JSON file's shape โ no route definitions, no ORM, no migrations to write.
- โQuery operators (eq, ne, lt, lte, gt, gte, in, contains, startsWith, endsWith) cover most filtering a frontend actually needs during development.
- โPagination returns real metadata (first/prev/next/last/pages/items), closer to what a production API's pagination response looks like than a hand-rolled mock.
- โMIT license, so there's no licensing friction for using it in any project.
- โStatic file serving from ./public is built in, so a demo can serve HTML/CSS/JS assets alongside API data from the same process.
Understanding JSON-Server's Scope
- โณThere's no authentication, authorization, or validation layer. Anyone who can reach the server can read and write every resource.
- โณThe current README documents the v1 beta, which the project itself flags as usable but subject to breaking changes; the stable release is v0.17.4 on a separate branch.
- โณIt's a development and testing tool, not something the README positions for production traffic.
- โณThe v0-to-v1 migration changes real behavior: IDs are now always strings and auto-generated, _limit is replaced by _page/_per_page, _expand is replaced by _embed, and the --delay flag is gone in favor of browser DevTools throttling โ upgrading isn't a drop-in swap.
- โณBusiness logic beyond CRUD and querying isn't something the tool provides; anything custom means writing your own middleware or moving off json-server.
Alternatives to JSON-Server
Frequently Asked Questions
JSON-Server is built and documented as a development and testing tool, not a production data layer. It has no authentication or validation layer of its own, so treat it as something you run locally or in CI rather than serve to real users.
JSON-Server is released under the MIT license, according to its GitHub repository.
You define API data in a db.json file (db.json5 also works) where each top-level key is a resource: an array like posts becomes full CRUD routes, and a plain object like profile becomes a single-object resource with GET/PUT/PATCH.
JSON-Server supports a _where parameter beyond simple field:operator filters. It accepts a raw JSON object for boolean logic such as OR conditions across multiple fields, and overrides the simpler query params when it's present.
JSON-Server serves files from a ./public directory without extra config, and the -s flag lets you add further static directories such as ./static or ./node_modules.
The v1 migration makes ids always strings with auto-generation, replaces the deprecated _limit parameter with _page/_per_page, replaces _expand with _embed for relations, and drops the --delay CLI flag in favor of browser DevTools network throttling.
The problem it solves
Frontend work usually stalls until a real backend exists, or teams write ad hoc fetch mocks that drift from actual HTTP behavior โ wrong status codes, no real pagination, no real query string parsing. JSON-Server turns a single JSON file into routes that respond like a real REST API, including status-appropriate CRUD, operator-based filtering, and pagination metadata, so frontend and test code can hit real HTTP endpoints before a backend team ships anything.
Who should try it โ and who should skip
Reach for JSON-Server if you're building a frontend or writing tests and want real HTTP requests against CRUD routes without standing up a database and backend framework. It fits teams that need filtering, sorting, and pagination behavior to look and feel real during development. Skip it if you need authentication, authorization, or business rules enforced server-side โ that's outside what a JSON-file-backed mock server is built to do, and you'll end up bolting on middleware or moving to a real backend anyway.
Related repositories
Curious whether json-server is right for you?
Let ChatGPT, Claude, or Perplexity look into it โ click below and see what AI actually says about json-server.