json-server

typicode/json-server

README

JSON Server


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

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

Egghead.io free video tutorial - Creating demo APIs with json-server
JSONPlaceholder - Live running version
My JSON Server - no installation required, use your own data

See also:

🐶* husky - Git hooks made easy
🦉* lowdb - local JSON database
✅* xv - a beautifully simple and capable test runner

Gold sponsors 🥇


Silver sponsors 🥈


Become a sponsor and have your company logo here

Sponsor


Please help me build OSS👉GitHub Sponsors ❤️

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

  1. ``` sh
  2. npm install -g json-server

  4. ```

Create a db.json file with some data

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

Start JSON Server

  1. ``` shell
  2. json-server --watch db.json
  3. ```

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

  1. ``` json
  2. { "id": 1, "title": "json-server", "author": "typicode" }
  3. ```

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


  1. ``` sh
  2. GET    /posts
  3. GET    /posts/1
  4. POST   /posts
  5. PUT    /posts/1
  6. PATCH  /posts/1
  7. DELETE /posts/1

  9. ```

Singular routes


  1. ``` sh
  2. GET    /profile
  3. POST   /profile
  4. PUT    /profile
  5. PATCH  /profile

  7. ```

Filter


Use . to access deep properties

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

  6. ```

Paginate


Use _page and optionally _limit to paginate returned data.

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

  1. ``` sh
  2. GET /posts?_page=7
  3. GET /posts?_page=7&_limit=20

  5. ```

10 items are returned by default

Sort


Add _sort and _order (ascending order by default)

  1. ``` sh
  2. GET /posts?_sort=views&_order=asc
  3. GET /posts/1/comments?_sort=votes&_order=asc

  5. ```

For multiple fields, use the following format:

  1. ``` sh
  2. GET /posts?_sort=user,views&_order=desc,asc

  4. ```

Slice


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

  1. ``` sh
  2. GET /posts?_start=20&_end=30
  3. GET /posts/1/comments?_start=20&_end=30
  4. GET /posts/1/comments?_start=20&_limit=10

  6. ```

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

Operators


Add _gte or _lte for getting a range

  1. ``` sh
  2. GET /posts?views_gte=10&views_lte=20

  4. ```

Add _ne to exclude a value

  1. ``` sh
  2. GET /posts?id_ne=1

  4. ```

Add _like to filter (RegExp supported)

  1. ``` sh
  2. GET /posts?title_like=server

  4. ```

Full-text search


Add q

  1. ``` sh
  2. GET /posts?q=internet

  4. ```

Relationships


To include children resources, add _embed

  1. ``` sh
  2. GET /posts?_embed=comments
  3. GET /posts/1?_embed=comments

  5. ```

To include parent resource, add _expand

  1. ``` sh
  2. GET /comments?_expand=post
  3. GET /comments/1?_expand=post

  5. ```

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

  1. ``` sh
  2. GET  /posts/1/comments
  3. POST /posts/1/comments

  5. ```

Database


  1. ``` sh
  2. GET /db

  4. ```

Homepage


Returns default index file or serves ./public directory

  1. ``` sh
  2. GET /

  4. ```

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.

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

  1. ``` shell
  2. json-server db.json --static ./some-other-dir
  3. ```

Alternative port


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

  1. ``` shell
  2. $ json-server --watch db.json --port 3004
  3. ```

Access from anywhere


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

Remote schema


You can load remote schemas.

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

Generate random data


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

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

  1. ``` shell
  2. $ json-server index.js
  3. ```

Tipuse 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. ``` json
  2. {
  3.   "/api/*": "/$1",
  4.   "/:resource/:id/show": "/:resource/:id",
  5.   "/posts/:category": "/posts?category=:category",
  6.   "/articles\\?id=:id": "/posts/:id"
  7. }
  8. ```

Start JSON Server with --routes option.

  1. ``` shell
  2. json-server db.json --routes routes.json
  3. ```

Now you can access resources using additional routes.

  1. ``` shell
  2. /api/posts # → /posts
  3. /api/posts/1  # → /posts/1
  4. /posts/1/show # → /posts/1
  5. /posts/javascript # → /posts?category=javascript
  6. /articles?id=1 # → /posts/1
  7. ```

Add middlewares


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

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

  1. ``` shell
  2. json-server db.json --middlewares ./hello.js
  3. json-server db.json --middlewares ./first.js ./second.js
  4. ```

CLI usage


  1. ``` sh
  2. json-server [options] <source>

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

  24. Examples:
  25.   json-server db.json
  26.   json-server file.js
  27.   json-server http://example.com/db.json

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

  31. ```

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

  1. ``` json
  2. {
  3.   "port": 3000
  4. }
  5. ```

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. ``` shell
  2. $ npm install json-server --save-dev
  3. ```

  1. ``` js
  2. // server.js
  3. const jsonServer = require('json-server')
  4. const server = jsonServer.create()
  5. const router = jsonServer.router('db.json')
  6. const middlewares = jsonServer.defaults()

  8. server.use(middlewares)
  9. server.use(router)
  10. server.listen(3000, () => {
  11.   console.log('JSON Server is running')
  12. })
  13. ```

  1. ``` shell
  2. $ node server.js
  3. ```

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:

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

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.

  1. ``` js
  2. const jsonServer = require('json-server')
  3. const server = jsonServer.create()
  4. const router = jsonServer.router('db.json')
  5. const middlewares = jsonServer.defaults()

  7. // Set default middlewares (logger, static, cors and no-cache)
  8. server.use(middlewares)

  10. // Add custom routes before JSON Server router
  11. server.get('/echo', (req, res) => {
  12.   res.jsonp(req.query)
  13. })

  15. // To handle POST, PUT and PATCH you need to use a body-parser
  16. // You can use the one used by JSON Server
  17. server.use(jsonServer.bodyParser)
  18. server.use((req, res, next) => {
  19.   if (req.method === 'POST') {
  20.     req.body.createdAt = Date.now()
  21.   }
  22.   // Continue to JSON Server router
  23.   next()
  24. })

  26. // Use default router
  27. server.use(router)
  28. server.listen(3000, () => {
  29.   console.log('JSON Server is running')
  30. })
  31. ```

Access control example


  1. ``` js
  2. const jsonServer = require('json-server')
  3. const server = jsonServer.create()
  4. const router = jsonServer.router('db.json')
  5. const middlewares = jsonServer.defaults()

  7. server.use(middlewares)
  8. server.use((req, res, next) => {
  9. if (isAuthorized(req)) { // add your authorization logic here
  10.    next() // continue to JSON Server router
  11. } else {
  12.    res.sendStatus(401)
  13. }
  14. })
  15. server.use(router)
  16. server.listen(3000, () => {
  17.   console.log('JSON Server is running')
  18. })
  19. ```

Custom output example


To modify responses, overwrite router.render method:

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

You can set your own status code for the response:

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

Rewriter example


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

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

Mounting JSON Server on another endpoint example


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

  1. ``` js
  2. server.use('/api', router)
  3. ```

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
Create a Mock REST API in Seconds for Prototyping your Frontend
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 ✨