json-server

[![Node.js CI](https://github.com/typicode/json-server/actions/workflows/node.js.yml/badge.svg)](https://github.com/typicode/json-server/actions/workflows/node.js.yml)

MIT 165 个版本
JSON server fake REST API prototyping mock mocking test testing rest data dummy
主页
仓库
提交 Issue
安装
npm install json-server
yarn add json-server
pnpm add json-server
bun add json-server
README

JSON-Server

Node.js CI

[!IMPORTANT] Viewing beta v1 documentation – usable but expect breaking changes. For stable version, see here

[!NOTE] Using React ⚛️ and tired of CSS-in-JS? See MistCSS 👀

Install

npm install json-server

Usage

Create a db.json or db.json5 file

{
  "$schema": "./node_modules/json-server/schema.json",
  "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"
  }
}
View db.json5 example 
{
  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",
  },
}

You can read more about JSON5 format here.

Start JSON Server

npx json-server db.json

This starts the server at http://localhost:3000. You should see:

JSON Server started on PORT :3000
http://localhost:3000

Access your REST API:

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

Response:

{
  "id": "1",
  "title": "a title",
  "views": 100
}

Run json-server --help for a list of options

Sponsors ✨

Gold
tower-dock-icon-light

Silver

Bronze

Become a sponsor and have your company logo here

Query Capabilities

JSON Server supports advanced querying out of the box:

GET /posts?views:gt=100                  # Filter by condition
GET /posts?_sort=-views                  # Sort by field (descending)
GET /posts?_page=1&_per_page=10          # Pagination
GET /posts?_embed=comments               # Include relations
GET /posts?_where={"or":[...]}           # Complex queries

See detailed documentation below for each feature.

Routes

Array Resources

For array resources like posts and comments:

GET    /posts
GET    /posts/:id
POST   /posts
PUT    /posts/:id
PATCH  /posts/:id
DELETE /posts/:id

Object Resources

For singular object resources like profile:

GET   /profile
PUT   /profile
PATCH /profile

Query params

Conditions

Use field:operator=value.

Operators:

  • no operator -> eq (equal)
  • lt less than, lte less than or equal
  • gt greater than, gte greater than or equal
  • eq equal, ne not equal
  • in included in comma-separated list
  • contains string contains (case-insensitive)
  • startsWith string starts with (case-insensitive)
  • endsWith string ends with (case-insensitive)

Examples:

GET /posts?views:gt=100
GET /posts?title:eq=Hello
GET /posts?id:in=1,2,3
GET /posts?author.name:eq=typicode
GET /posts?title:contains=hello
GET /posts?title:startsWith=Hello
GET /posts?title:endsWith=world

Sort

GET /posts?_sort=title
GET /posts?_sort=-views
GET /posts?_sort=author.name,-views

Pagination

GET /posts?_page=1&_per_page=25

Response:

{
  "first": 1,
  "prev": null,
  "next": 2,
  "last": 4,
  "pages": 4,
  "items": 100,
  "data": [
    { "id": "1", "title": "...", "views": 100 },
    { "id": "2", "title": "...", "views": 200 }
  ]
}

Notes:

  • _per_page defaults to 10 if not specified
  • Invalid _page or _per_page values are automatically normalized to valid ranges

Embed

GET /posts?_embed=comments
GET /comments?_embed=post

Complex filter with _where

_where accepts a JSON object and overrides normal query params when valid.

GET /posts?_where={"or":[{"views":{"gt":100}},{"author":{"name":{"lt":"m"}}}]}

Delete dependents

DELETE /posts/1?_dependent=comments

Static Files

JSON Server automatically serves files from the ./public directory.

To serve additional static directories:

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

Static files are served with standard MIME types and can include HTML, CSS, JavaScript, images, and other assets.

Migration Notes (v0 → v1)

If you are upgrading from json-server v0.x, note these behavioral changes:

  • ID handling: id is always a string and will be auto-generated if not provided
  • Pagination: Use _per_page with _page instead of the deprecated _limit parameter
  • Relationships: Use _embed instead of _expand for including related resources
  • Request delays: Use browser DevTools (Network tab > throttling) instead of the removed --delay CLI option

New to json-server? These notes are for users migrating from v0. If this is your first time using json-server, you can ignore this section.

版本列表
1.0.0-beta.15 2026-03-23
1.0.0-beta.14 2026-03-20
1.0.0-beta.13 2026-03-13
1.0.0-beta.12 2026-02-28
1.0.0-beta.10 2026-02-26
1.0.0-beta.9 2026-02-19
1.0.0-beta.8 2026-02-19
1.0.0-beta.7 2026-02-19
1.0.0-beta.6 2026-02-14
1.0.0-beta.5 2026-01-22
1.0.0-beta.4 2026-01-21
1.0.0-beta.3 2024-09-24
1.0.0-beta.2 2024-08-19
1.0.0-beta.1 2024-06-04
1.0.0-beta.0 2024-05-13
1.0.0-alpha.23 2024-01-26
1.0.0-alpha.22 2024-01-22
1.0.0-alpha.21 2024-01-13
1.0.0-alpha.20 2024-01-13
1.0.0-alpha.19 2024-01-12
1.0.0-alpha.18 2024-01-11
1.0.0-alpha.17 2024-01-11
1.0.0-alpha.16 2024-01-09
1.0.0-alpha.15 2024-01-09
1.0.0-alpha.14 2024-01-09
1.0.0-alpha.13 2024-01-07
1.0.0-alpha.12 2024-01-07
1.0.0-alpha.11 2024-01-07
1.0.0-alpha.10 2024-01-05
1.0.0-alpha.9 2024-01-02
1.0.0-alpha.8 2023-12-30
1.0.0-alpha.7 2023-12-30
1.0.0-alpha.6 2023-12-28
1.0.0-alpha.5 2023-12-27
1.0.0-alpha.4 2023-12-26
1.0.0-alpha.3 2023-12-17
1.0.0-alpha.1 2023-12-17
0.17.4 2023-09-29
0.17.3 2023-03-21
0.17.2 2023-02-22
0.17.1 2022-11-03
0.17.0 2021-10-06
0.16.3 2020-11-15
0.16.2 2020-09-30
0.16.1 2020-02-23
0.16.0 2020-02-12
0.15.1 2019-09-02
0.15.0 2019-05-21
0.14.2 2018-12-26
0.14.1 2018-12-25
0.14.0 2018-06-08
0.13.0 2018-05-30
0.12.2 2018-04-26
0.12.1 2017-11-02
0.12.0 2017-08-02
0.11.2 2017-07-10
0.11.1 2017-07-10
0.11.0 2017-07-05
0.10.3 2017-06-28
0.10.2 2017-06-28
0.10.1 2017-05-15
0.10.0 2017-04-26
0.9.6 2017-03-08
0.9.5 2017-02-10
0.9.4 2016-12-08
0.9.3 2016-12-07
0.9.2 2016-11-29
0.9.1 2016-11-21
0.9.0-beta.2 2016-10-12
0.9.0-beta.1 2016-10-12
0.9.0 2016-11-12
0.8.23 2016-11-03
0.8.22 2016-10-04
0.8.21 2016-09-13
0.8.20 2016-09-12
0.8.19 2016-08-30
0.8.18 2016-08-17
0.8.17 2016-07-25
0.8.16 2016-07-11
0.8.15 2016-07-03
0.8.14 2016-05-15
0.8.13 2016-05-12
0.8.12 2016-05-08
0.8.11 2016-05-08
0.8.10 2016-04-18
0.8.9 2016-03-17
0.8.8 2016-02-13
0.8.7 2016-01-22
0.8.6 2016-01-07
0.8.5 2015-12-28
0.8.4 2015-12-13
0.8.3 2015-11-29
0.8.2 2015-10-15
0.8.1 2015-10-06
0.8.0 2015-09-21
0.7.28 2015-09-09
0.7.27 2015-09-02
0.7.26 2015-09-01
0.7.25 2015-08-04
0.7.24 2015-07-31
0.7.23 2015-07-23
0.7.21 2015-07-15
0.7.20 2015-06-26
0.7.19 2015-06-20
0.7.18 2015-06-18
0.7.17 2015-06-16
0.7.16 2015-06-15
0.7.15 2015-06-15
0.7.14 2015-06-11
0.7.13 2015-06-04
0.7.12 2015-06-01
0.7.11 2015-05-27
0.7.10 2015-05-25
0.7.9 2015-05-22
0.7.8 2015-05-15
0.7.7 2015-05-15
0.7.6 2015-05-13
0.7.5 2015-05-12
0.7.4 2015-05-07
0.7.3 2015-05-04
0.7.2 2015-04-26
0.7.1 2015-04-21
0.7.0 2015-04-17
0.6.10 2015-04-17
0.6.9 2015-04-12
0.6.8 2015-04-04
0.6.7 2015-04-03
0.6.6 2015-03-24
0.6.5 2015-03-23
0.6.4 2015-03-16
0.6.3 2015-03-05
0.6.2 2015-02-10
0.6.1 2015-02-06
0.6.0 2015-02-06
0.5.12 2015-02-04
0.5.11 2015-02-03
0.5.10 2015-01-24
0.5.9 2015-01-08
0.5.8 2015-01-08
0.5.7 2015-01-07
0.5.6 2015-01-06
0.5.5 2014-11-16
0.5.4 2014-10-23
0.5.2 2014-10-20
0.5.1 2014-10-20
0.5.0 2014-10-13
0.4.2 2014-10-06
0.4.1 2014-09-30
0.4.0 2014-09-18
0.3.11 2014-08-07
0.3.10 2014-08-07
0.3.9 2014-06-26
0.3.8 2014-06-24
0.3.7 2014-06-12
0.3.6 2014-05-12
0.3.5 2014-05-12
0.3.4 2014-05-09
0.3.3 2014-05-09
0.3.2 2014-05-06
0.3.1 2014-04-14
0.3.0 2014-04-11
0.2.0 2013-12-29
0.1.1 2013-12-16
0.1.0 2013-12-03
0.0.0 2013-12-03