/json-server

REST API mocking based on plain JSON

Primary LanguageJavaScriptMIT LicenseMIT

JSON Server Build Status NPM version

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

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

Powers JSONPlaceholder

Usage

CLI

Create a db.json file:

{
  "posts": [
    { "id": 1, "body": "foo" }
  ]
}

Then run json-server db.json and go to http://localhost:3000/posts/1.

You should get { "id": 1, "body": "foo" }.

Module

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

server({
  posts: [
    { id: 1, body: 'foo' }
  ]
}).listen(3000);

Features

  • 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 (JSON Generator, ...)
  • Can be deployed on Nodejitsu, Heroku, ...

Install

$ npm install -g json-server

CLI options

json-server <source>

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


Options:
  --help, -h     Show help
  --version, -v  Show version number
  --port, -p     Set port             [default: 3000]

Input

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

JSON

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

JS

module.exports = function() {
  var data = {};

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

  return data;
}

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

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

Available routes

Let's say we have posts, here's the routes you can use.

GET   /posts
GET   /posts?title=jsonserver&author=typicode
GET   /posts/1/comments
GET   /posts/1
POST  /posts
PUT   /posts/1
PATCH /posts/1
DEL   /posts/1

To slice resources, add _start and _end.

GET /posts?_start=0&_end=10
GET /posts/1/comments?_start=0&_end=10

To sort resources, add _sort and _order (ascending order by default).

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

To make a full-text search on resources, add q.

GET /posts?q=internet

Returns database.

GET /db

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

GET /

For more routes usage examples, have a look at JSONPlaceholder's README.

Links

Articles

Projects