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
What is this?json-server lets you spin up a fully working fake REST API in under 30 seconds, with no backend code to write — just a single JSON file defining your data.
Is this a library I import or a standalone CLI tool?It's a standalone command-line tool. You point it at a JSON file and it immediately serves REST endpoints; there's nothing to import into your own code.
How do I get it running?Create a db.json or db.json5 file describing your resources (e.g. posts, comments), then start json-server pointing at that file to launch the server locally.
What do I need installed first?You need Node.js 22.12 or newer, since that's the minimum engine version json-server requires to run.
Is the current documentation stable?You're looking at beta v1 docs — it's usable day to day, but the README warns breaking changes can still happen before it's finalized; a separate stable version exists for production use.
What kind of queries can I run against the fake API?You can filter with field:operator=value using operators like eq, ne, lt, lte, gt, gte, in, contains, startsWith and endsWith, plus sort results, paginate with page/perpage, and run complex filters via a JSON where object.
Can it serve anything besides the JSON API?Yes — json-server automatically serves static files from a ./public directory out of the box, and you can register additional static directories for HTML, CSS, JS, or images.
How do I model relationships between resources?Array resources like posts and comments can be embedded in responses using the embed query param, which replaces the older expand option from v0.
What changed if I'm upgrading from the old v0 version?IDs are now always strings and auto-generated if missing, pagination uses perpage+page instead of the old limit param, expand was replaced by embed, and the --delay CLI flag was removed in favor of browser DevTools network throttling.
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