This code is modified based on typicode/json-server. Used to change some features, if these features are liked, they will apply to typicode for a merge.

Install

1npm i @wll8/json-server 
2# or npm i -g @wll8/json-server

jsonServer.defaults

Now you can customize the size of the request body

1jsonServer.defaults({
2  bodyParser: [
3    bodyParser.json({
4      limit: `100mb`,
5      extended: false,
6    }),
7    bodyParser.urlencoded({
8      extended: false,
9    }),
10  ]
11})

• issues: #38, #37

express

At present, it seems that json-server relies heavily on express and is inconvenient to upgrade, so using its dependencies directly will make me install one less package

1const {lib: { express }} = jsonServer

options._preciseNeste

Optional exact table name matching when nesting routes

• type: boolean
• Defaults: false

For example, when requesting /postxx/xxx/comments, when _preciseNeste is false, it will be processed as /comments?postxxId=xxx. When _preciseNeste is true, no processing will be done because postxx is not a table.

options._noRemoveDependents

After deleting data, do not clean up data that are not related to each other

• type: boolean
• Defaults: false
• issues: #885

options._noDataNext

Allows entry to the next route when there is no data, which makes it work seamlessly with other programs

• type: boolean
• Defaults: false
• issues: #1330

options._noDbRoute

Assuming a db.json data breach poses a risk, it can be turned off with this option

• type: boolean
• Defaults: false

JSON Server

Get a full fake REST API with zero coding in less than 30 seconds (seriously)

Created with <3 for front-end developers who need a quick back-end for prototyping and mocking.

[!NOTE] Try JSON Server v1-alpha here 🚀

• JSONPlaceholder - Live running version
• My JSON Server - no installation required, use your own data

See also:

• :dog: husky - Git hooks made easy
• :owl: lowdb - local JSON database

 

Gold sponsors

 

 

Silver sponsors

 

Bronze sponsors

 

 

 

Become a sponsor and have your company logo here

Sponsor

Please help me build OSS 👉 GitHub Sponsors :heart:

Table of contents

• JSON Server
  • Sponsor
  • Table of contents
  • Getting started
  • Routes
    • Plural routes
    • Singular routes
    • Filter
    • Paginate
    • Sort
    • Slice
    • Operators
    • Full-text search
    • Relationships
    • Database
    • Homepage
  • Extras
    • Static file server
    • Alternative port
    • Access from anywhere
    • Remote schema
    • Generate random data
    • HTTPS
    • Add custom routes
    • Add middlewares
    • CLI usage
    • Module
      • Simple example
      • Custom routes example
      • Access control example
      • Custom output example
      • Rewriter example
      • Mounting JSON Server on another endpoint example
      • API
    • Deployment
  • Links
    • Video
    • Articles
    • Third-party tools
  • License

Getting started

Install JSON Server

npm install -g json-server@0.17.4    # NPM
yarn global add json-server@0.17.4   # Yarn
pnpm add -g json-server@0.17.4       # PNPM

Create a db.json file with some data

1{
2  "posts": [
3    { "id": 1, "title": "json-server", "author": "typicode" }
4  ],
5  "comments": [
6    { "id": 1, "body": "some comment", "postId": 1 }
7  ],
8  "profile": { "name": "typicode" }
9}

Start JSON Server

1json-server --watch db.json

Now if you go to http://localhost:3000/posts/1, you'll get

1{ "id": 1, "title": "json-server", "author": "typicode" }

Also when doing requests, it's good to know that:

• If you make POST, PUT, PATCH or DELETE requests, changes will be automatically and safely saved to db.json using lowdb.
• Your request body JSON should be object enclosed, just like the GET output. (for example {"name": "Foobar"})
• Id values are not mutable. Any id value in the body of your PUT or PATCH request will be ignored. Only a value set in a POST request will be respected, but only if not already taken.
• A POST, PUT or PATCH request should include a Content-Type: application/json header to use the JSON in the request body. Otherwise it will return a 2XX status code, but without changes being made to the data.

Routes

Based on the previous db.json file, here are all the default routes. You can also add other routes using --routes.

Plural routes

GET    /posts
GET    /posts/1
POST   /posts
PUT    /posts/1
PATCH  /posts/1
DELETE /posts/1

Singular routes

GET    /profile
POST   /profile
PUT    /profile
PATCH  /profile

Filter

Use . to access deep properties

GET /posts?title=json-server&author=typicode
GET /posts?id=1&id=2
GET /comments?author.name=typicode

Paginate

Use _page and optionally _limit to paginate returned data.

In the Link header you'll get first, prev, next and last links.

GET /posts?_page=7
GET /posts?_page=7&_limit=20

10 items are returned by default

Sort

Add _sort and _order (ascending order by default)

GET /posts?_sort=views&_order=asc
GET /posts/1/comments?_sort=votes&_order=asc

For multiple fields, use the following format:

GET /posts?_sort=user,views&_order=desc,asc

Slice

Add _start and _end or _limit (an X-Total-Count header is included in the response)

GET /posts?_start=20&_end=30
GET /posts/1/comments?_start=20&_end=30
GET /posts/1/comments?_start=20&_limit=10

Works exactly as Array.slice (i.e. _start is inclusive and _end exclusive)

Operators

Add _gte or _lte for getting a range

GET /posts?views_gte=10&views_lte=20

Add _ne to exclude a value

GET /posts?id_ne=1

Add _like to filter (RegExp supported)

GET /posts?title_like=server

Full-text search

Add q

GET /posts?q=internet

Relationships

To include children resources, add _embed

GET /posts?_embed=comments
GET /posts/1?_embed=comments

To include parent resource, add _expand

GET /comments?_expand=post
GET /comments/1?_expand=post

To get or create nested resources (by default one level, add custom routes for more)

GET  /posts/1/comments
POST /posts/1/comments

Database

GET /db

Homepage

Returns default index file or serves ./public directory

GET /

Extras

Static file server

You can use JSON Server to serve your HTML, JS and CSS, simply create a ./public directory or use --static to set a different static files directory.

1mkdir public
2echo 'hello world' > public/index.html
3json-server db.json

1json-server db.json --static ./some-other-dir

Alternative port

You can start JSON Server on other ports with the --port flag:

1$ json-server --watch db.json --port 3004

Access from anywhere

You can access your fake API from anywhere using CORS and JSONP.

Remote schema

You can load remote schemas.

1$ json-server http://example.com/file.json
2$ json-server http://jsonplaceholder.typicode.com/db

Generate random data

Using JS instead of a JSON file, you can create data programmatically.

1// index.js
2module.exports = () => {
3  const data = { users: [] }
4  // Create 1000 users
5  for (let i = 0; i < 1000; i++) {
6    data.users.push({ id: i, name: `user${i}` })
7  }
8  return data
9}

1$ json-server index.js

Tip use modules like Faker, Casual, Chance or JSON Schema Faker.

HTTPS

There are many ways to set up SSL in development. One simple way is to use hotel.

Add custom routes

Create a routes.json file. Pay attention to start every route with /.

1{
2  "/api/*": "/$1",
3  "/:resource/:id/show": "/:resource/:id",
4  "/posts/:category": "/posts?category=:category",
5  "/articles?id=:id": "/posts/:id"
6}

Start JSON Server with --routes option.

1json-server db.json --routes routes.json

Now you can access resources using additional routes.

1/api/posts # → /posts
2/api/posts/1  # → /posts/1
3/posts/1/show # → /posts/1
4/posts/javascript # → /posts?category=javascript
5/articles?id=1 # → /posts/1

Add middlewares

You can add your middlewares from the CLI using --middlewares option:

1// hello.js
2module.exports = (req, res, next) => {
3  res.header('X-Hello', 'World')
4  next()
5}

1json-server db.json --middlewares ./hello.js
2json-server db.json --middlewares ./first.js ./second.js

CLI usage

json-server [options] <source>

Options:
  --config, -c       Path to config file           [default: "json-server.json"]
  --port, -p         Set port                                    [default: 3000]
  --host, -H         Set host                             [default: "localhost"]
  --watch, -w        Watch file(s)                                     [boolean]
  --routes, -r       Path to routes file
  --middlewares, -m  Paths to middleware files                           [array]
  --static, -s       Set static files directory
  --read-only, --ro  Allow only GET requests                           [boolean]
  --no-cors, --nc    Disable Cross-Origin Resource Sharing             [boolean]
  --no-gzip, --ng    Disable GZIP Content-Encoding                     [boolean]
  --snapshots, -S    Set snapshots directory                      [default: "."]
  --delay, -d        Add delay to responses (ms)
  --id, -i           Set database id property (e.g. _id)         [default: "id"]
  --foreignKeySuffix, --fks  Set foreign key suffix, (e.g. _id as in post_id)
                                                                 [default: "Id"]
  --quiet, -q        Suppress log messages from output                 [boolean]
  --help, -h         Show help                                         [boolean]
  --version, -v      Show version number                               [boolean]

Examples:
  json-server db.json
  json-server file.js
  json-server http://example.com/db.json

https://github.com/typicode/json-server

You can also set options in a json-server.json configuration file.

1{
2  "port": 3000
3}

Module

If you need to add authentication, validation, or any behavior, you can use the project as a module in combination with other Express middlewares.

Simple example

1$ npm install json-server --save-dev

1// server.js
2const jsonServer = require('json-server')
3const server = jsonServer.create()
4const router = jsonServer.router('db.json')
5const middlewares = jsonServer.defaults()
6
7server.use(middlewares)
8server.use(router)
9server.listen(3000, () => {
10  console.log('JSON Server is running')
11})

1$ node server.js

The path you provide to the jsonServer.router function is relative to the directory from where you launch your node process. If you run the above code from another directory, it’s better to use an absolute path:

1const path = require('path')
2const router = jsonServer.router(path.join(__dirname, 'db.json'))

For an in-memory database, simply pass an object to jsonServer.router().

To add custom options (eg. foreginKeySuffix) pass in an object as the second argument to jsonServer.router('db.json', { foreginKeySuffix: '_id' }).

Please note also that jsonServer.router() can be used in existing Express projects.

Custom routes example

Let's say you want a route that echoes query parameters and another one that set a timestamp on every resource created.

1const jsonServer = require('json-server')
2const server = jsonServer.create()
3const router = jsonServer.router('db.json')
4const middlewares = jsonServer.defaults()
5
6// Set default middlewares (logger, static, cors and no-cache)
7server.use(middlewares)
8
9// Add custom routes before JSON Server router
10server.get('/echo', (req, res) => {
11  res.jsonp(req.query)
12})
13
14// To handle POST, PUT and PATCH you need to use a body-parser
15// You can use the one used by JSON Server
16server.use(jsonServer.bodyParser)
17server.use((req, res, next) => {
18  if (req.method === 'POST') {
19    req.body.createdAt = Date.now()
20  }
21  // Continue to JSON Server router
22  next()
23})
24
25// Use default router
26server.use(router)
27server.listen(3000, () => {
28  console.log('JSON Server is running')
29})

Access control example

1const jsonServer = require('json-server')
2const server = jsonServer.create()
3const router = jsonServer.router('db.json')
4const middlewares = jsonServer.defaults()
5
6server.use(middlewares)
7server.use((req, res, next) => {
8 if (isAuthorized(req)) { // add your authorization logic here
9   next() // continue to JSON Server router
10 } else {
11   res.sendStatus(401)
12 }
13})
14server.use(router)
15server.listen(3000, () => {
16  console.log('JSON Server is running')
17})

Custom output example

To modify responses, overwrite router.render method:

1// In this example, returned resources will be wrapped in a body property
2router.render = (req, res) => {
3  res.jsonp({
4    body: res.locals.data
5  })
6}

You can set your own status code for the response:

1// In this example we simulate a server side error response
2router.render = (req, res) => {
3  res.status(500).jsonp({
4    error: "error message here"
5  })
6}

Rewriter example

To add rewrite rules, use jsonServer.rewriter():

1// Add this before server.use(router)
2server.use(jsonServer.rewriter({
3  '/api/*': '/$1',
4  '/blog/:resource/:id/show': '/:resource/:id'
5}))

Mounting JSON Server on another endpoint example

Alternatively, you can also mount the router on /api.

1server.use('/api', router)

API

jsonServer.create()

Returns an Express server.

jsonServer.defaults([options])

Returns middlewares used by JSON Server.

• options
  • static path to static files
  • logger enable logger middleware (default: true)
  • bodyParser enable body-parser middleware (default: true)
  • noCors disable CORS (default: false)
  • readOnly accept only GET requests (default: false)

jsonServer.router([path|object], [options])

Returns JSON Server router.

• options (see CLI usage)

Deployment

You can deploy JSON Server. For example, JSONPlaceholder is an online fake API powered by JSON Server and running on Heroku.

Links

Video

• Creating Demo APIs with json-server on egghead.io

Articles

• Node Module Of The Week - json-server
• ng-admin: Add an AngularJS admin GUI to any RESTful API
• Fast prototyping using Restangular and Json-server
• No API? No Problem! Rapid Development via Mock APIs
• Zero Code REST With json-server

Third-party tools

• Grunt JSON Server
• Docker JSON Server
• JSON Server GUI
• JSON file generator
• JSON Server extension

License

MIT

Supporters ✨