# json-server
**Repository Path**: anydev/json-server
## Basic Information
- **Project Name**: json-server
- **Description**: JSON Server 是一个用于快速创建模拟 REST API 的 Node.js 工具，无需编写任何后端代码。允许您通过一个简单的 JSON 文件快速搭建一个功能完整的 REST API 服务器，支持所有标准的 CRUD（创建、读取、更新、删除）操作，并内置了高级查询功能。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-08
- **Last Updated**: 2026-04-08
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# JSON-Server
[](https://github.com/typicode/json-server/actions/workflows/node.js.yml)
> [!IMPORTANT]
> Viewing beta v1 documentation – usable but expect breaking changes. For stable version, see [here](https://github.com/typicode/json-server/tree/v0.17.4)
> [!NOTE]
> Using React ⚛️ and tired of CSS-in-JS? See [MistCSS](https://github.com/typicode/mistcss) 👀
## Install
```shell
npm install json-server
```
## Usage
Create a `db.json` or `db.json5` file
```json
{
"$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
```json5
{
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](https://github.com/json5/json5).
Start JSON Server
```bash
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:
```bash
curl http://localhost:3000/posts/1
```
**Response:**
```json
{
"id": "1",
"title": "a title",
"views": 100
}
```
Run `json-server --help` for a list of options
## Sponsors ✨
### Gold
| |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------: |
| 
|
| 
|
| 
|
| 
|
| 
### Silver
| |
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| 
|
### Bronze
| | |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| 
| 
|
[Become a sponsor and have your company logo here](https://github.com/users/typicode/sponsorship)
## Query Capabilities
JSON Server supports advanced querying out of the box:
```http
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`:
```http
GET /posts
GET /posts/:id
POST /posts
PUT /posts/:id
PATCH /posts/:id
DELETE /posts/:id
```
### Object Resources
For singular object resources like `profile`:
```http
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:
```http
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
```http
GET /posts?_sort=title
GET /posts?_sort=-views
GET /posts?_sort=author.name,-views
```
### Pagination
```http
GET /posts?_page=1&_per_page=25
```
**Response:**
```json
{
"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
```http
GET /posts?_embed=comments
GET /comments?_embed=post
```
### Complex filter with `_where`
`_where` accepts a JSON object and overrides normal query params when valid.
```http
GET /posts?_where={"or":[{"views":{"gt":100}},{"author":{"name":{"lt":"m"}}}]}
```
## Delete dependents
```http
DELETE /posts/1?_dependent=comments
```
## Static Files
JSON Server automatically serves files from the `./public` directory.
To serve additional static directories:
```bash
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.