json-server

What is json-server?

json-server is a full fake REST API with zero coding in less than 30 seconds. It allows you to create a mock REST API using a simple JSON file as the database.

What are json-server's main functionalities?

Create a Fake REST API

This code sets up a basic JSON server that reads from a 'db.json' file and serves it as a REST API. The server listens on port 3000.

const jsonServer = require('json-server');
const server = jsonServer.create();
const router = jsonServer.router('db.json');
const middlewares = jsonServer.defaults();

server.use(middlewares);
server.use(router);
server.listen(3000, () => {
  console.log('JSON Server is running');
});

Custom Routes

This code demonstrates how to use custom routes with json-server. The rewriter middleware is used to map custom routes to the default routes.

const jsonServer = require('json-server');
const server = jsonServer.create();
const router = jsonServer.router('db.json');
const middlewares = jsonServer.defaults();

server.use(middlewares);
server.use(jsonServer.rewriter({
  '/api/*': '/$1',
  '/blog/:resource/:id/show': '/:resource/:id'
}));
server.use(router);
server.listen(3000, () => {
  console.log('JSON Server is running');
});

Add Custom Middleware

This code adds custom middleware to the JSON server. In this example, a timestamp is added to the request body for POST requests.

const jsonServer = require('json-server');
const server = jsonServer.create();
const router = jsonServer.router('db.json');
const middlewares = jsonServer.defaults();

server.use(middlewares);

server.use((req, res, next) => {
  if (req.method === 'POST') {
    req.body.createdAt = Date.now();
  }
  next();
});

server.use(router);
server.listen(3000, () => {
  console.log('JSON Server is running');
});

Other packages similar to json-server

miragejs

Mirage JS is a client-side server to build, test and share a complete working JavaScript application without having to rely on any backend services. Unlike json-server, which is more focused on quickly setting up a REST API, Mirage JS is designed to work seamlessly with frontend frameworks like React, Vue, and Angular.

prism

Prism is a package for creating mock servers based on OpenAPI and API Blueprint specifications. It allows you to create a mock server that can validate requests and responses against your API specification. Unlike json-server, which uses a JSON file as a database, Prism uses API specifications to generate mock responses.

README

json-server

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

👋 Hey! Using React, Vue or Astro? Check my new project MistCSS to write 50% less code.

Install

npm install json-server

Usage

Create a db.json or db.json5 file

{
  "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.

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

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

Sponsors ✨

Sponsors

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/.

Routes

Based on the example db.json, you'll get the following routes:

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

# Same for comments

GET   /profile
PUT   /profile
PATCH /profile

Params

Conditions

• → ==
• lt → <
• lte → <=
• gt → >
• gte → >=
• ne → !=

GET /posts?views_gt=9000

Range

• start
• end
• limit

GET /posts?_start=10&_end=20
GET /posts?_start=10&_limit=10

Paginate

• page
• per_page (default = 10)

GET /posts?_page=1&_per_page=25

Sort

• _sort=f1,f2

GET /posts?_sort=id,-views

Nested and array fields

• x.y.z...
• x.y.z[i]...

GET /foo?a.b=bar
GET /foo?x.y_lt=100
GET /foo?arr[0]=bar

Embed

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

Delete

DELETE /posts/1
DELETE /posts/1?_dependent=comments

Serving static files

If you create a ./public directory, JSON Serve will serve its content in addition to the REST API.

You can also add custom directories using -s/--static option.

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

Notable differences with v0.17

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