JSON-Server

[!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"
  }
}

{
  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",
  },
}

Pass it to JSON Server CLI

$ npx json-server db.json

Get a REST API

$ curl http://localhost:3000/posts/1
{
  "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

Sponsorware

[!NOTE] This project uses the Fair Source License. Only organizations with 3+ users are kindly asked to contribute a small amount through sponsorship sponsor for usage. This license helps keep the project sustainable and healthy, benefiting everyone.

For more information, FAQs, and the rationale behind this, visit https://fair.io/.

Query capabilities overview

GET /posts?views:gt=100
GET /posts?_sort=-views
GET /posts?_page=1&_per_page=10
GET /posts?_embed=comments
GET /posts?_where={"or":[{"views":{"gt":100}},{"title":{"eq":"Hello"}}]}

Routes

For array resources (posts, comments):

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

For object resources (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

Examples:

GET /posts?views:gt=100
GET /posts?title:eq=Hello
GET /posts?author.name:eq=typicode

Sort

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

Pagination

GET /posts?_page=1&_per_page=25

• _per_page default is 10
• invalid page/per_page values are normalized

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 serves ./public automatically.

Add more static dirs:

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

Behavior notes

• id is always a string and will be generated for you if missing
• use _per_page with _page instead of _limitfor pagination
• use _embed instead of _expand
• use Chrome's Network tab > throtling to delay requests instead of --delay CLI option