json-server README

The project's README from github.com/typicode/json-server. As one markdown file: README.md.

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:

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:

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:

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.

json-server (typicode/json-server)

Searching Database…

75.7K ·GitHub
Json-server
Что это такое?json-server позволяет за 30 секунд поднять полностью рабочий фейковый REST API без написания серверного кода. Достаточно одного JSON-файла, который описывает ваши данные.
Это библиотека, которую я подключаю в код, или отдельная CLI-утилита?Это самостоятельная утилита командной строки. Вы передаёте ей JSON-файл, и она сразу отдаёт REST-эндпоинты. Ничего импортировать в свой код не нужно.
Как это запустить?Создайте файл db.json или db.json5, который описывает ваши ресурсы (например, posts, comments), а затем запустите json-server с указанием этого файла, чтобы локально поднять сервер.
Что нужно установить заранее?Нужен Node.js версии 22.12 или новее, так как это минимальная версия движка, с которой json-server может работать.
Стабильна ли текущая документация?Вы смотрите документацию beta v1. Ей можно пользоваться каждый день, но в README предупреждается, что до финального релиза могут появиться несовместимые изменения. Для продакшена существует отдельная стабильная версия.
Какие запросы я могу выполнять к фейковому API?Можно фильтровать с помощью field:operator=value, используя операторы eq, ne, lt, lte, gt, gte, in, contains, startsWith и endsWith. Также можно сортировать результаты, делить их на страницы через page/perpage и задавать сложные фильтры через JSON-объект where.
Может ли она отдавать что-то кроме JSON API?Да. json-server по умолчанию автоматически отдаёт статические файлы из каталога ./public, а также можно подключить дополнительные статические каталоги для HTML, CSS, JS или изображений.
Как мне описать связи между ресурсами?Массивы ресурсов, например posts и comments, можно встраивать в ответы с помощью query-параметра embed. Он заменил старую опцию expand из v0.
Что изменилось, если я перехожу со старой версии v0?ID теперь всегда строки и генерируются автоматически, если их нет. Пагинация использует perpage+page вместо старого параметра limit. Опция expand заменена на embed, а CLI-флаг --delay удалён в пользу троттлинга сети в DevTools браузера.
What are similar projects?nock, msw, node-restify, ky, yapi, jest, cli, insomnia
Which topics is it in?fake, test, mocking, mock, rest, node, json, rest-api, command-line-tool, frontend, api, terminal
Creator
typicode
Size
4.2 MB
Stars
75.7K
Updated
CommitMar 23Releasev1.0.0-beta.15Mar 23
Age
12y
Commits · 90 Days