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

Give it a JSON or JS seed file and it will serve it through REST routes.

Created with :heart: for front-end developers who need a flexible back-end for quick prototyping and mocking.

Examples

Command line interface

$ cat db.json
{ 
  posts: [
    { id: 1, body: 'foo' }
  ]
}
$ json-server --file db.json
$ curl -i http://localhost:3000/posts/1

Node module

var server = require('json-server');

var db = {
  posts: [
    {id: 1, body: 'foo'}
  ]
}

server.run(db);

You can find a running demo here: http://jsonplaceholder.typicode.com.

Why?

• Lets you use plain JSON or simple JS file
• Supports GET but also POST, PUT, DELETE and even PATCH requests
• Can be used from anywhere through cross domain requests (JSONP or CORS)
• Can load remote JSON files
• Can be deployed on Nodejitsu, Heroku, ...

Installation

$ npm install -g json-server 

Usage

Command line interface

json-server --help

  Usage: json-server [options]

  Options:

    -h, --help        output usage information
    -V, --version     output the version number
    -f --file <file>  load db from a js or json file
    -u --url <url>    load db from a URL
    -p --port [port]  server port
    --read-only       read only mode

JSON Server can load JSON from multiple sources:

$ json-server --file db.json
$ json-server --file seed.js
$ json-server --url http://example.com/db.json

And be run in read-only mode (useful if deployed on a public server):

$ json-server --file db.json --read-only

Input

Here's 2 examples showing how to format JSON or JS seed file:

• db.json

{
  posts: [
    { id: 1, body: 'foo'},
    { id: 2, body: 'bar'}
  ],
  comments: [
    { id: 1, body: 'baz', postId: 1}
    { id: 2, body: 'qux', postId: 2}
  ]
}

• seed.js

exports.run = function() {
  var data = {};
  
  data.posts = [];
  data.posts.push({id: 1, body: 'foo'});
  //...

  return data;
}

JSON Server expects JS files to export a run method that returns an object.

Seed files are useful if you need to programmaticaly create a lot of data.

Node module

run(db, [options])

var server = require('json-server'),
    db = require('./seed').run();

var options = { port: 4000, readOnly: true };

server.run(db, options);

By default, port is set to 3000 and readOnly to false.

Routes

GET   /:resource
GET   /:resource?attr=&attr=&
GET   /:parent/:parentId/:resource
GET   /:resource/:id
POST  /:resource
PUT   /:resource/:id
PATCH /:resource/:id
DEL   /:resource/:id

For routes usage information, have a look at JSONPlaceholder code examples.

GET /db

Returns database state.

GET /

Returns default index file or content of ./public/index.html (useful if you need to set a custom home page).

Support

If you like the project, please tell your friends about it, star it or give feedback :) It's very much appreciated!

For project updates or to get in touch, @typicode. You can also send me a mail.

Test

$ npm install 
$ npm test