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.

• Egghead.io free video tutorial - Creating demo APIs with json-server
• JSONPlaceholder - Live running version

See also:

• 🏨 hotel - Start apps from your browser and get local dev domains in seconds
• 🐶 husky - Git hooks made easy

Create a db.json file

{"posts": [{"id": 1, "title": "json-server", "author": "typicode" } ], "comments": [{"id": 1, "body": "some comment", "postId": 1 } ], "profile":{"name": "typicode" } }

Start JSON Server

$ json-server --watch db.json

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

{"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 wil be ignored. Only a value set in a POST request wil 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 result in a 200 OK but without changes being made to the data.

$ npm install -g json-server

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

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

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

Use . to access deep properties

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

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

Add _sort and _order (ascending order by default)

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

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)

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 

Add q

GET /posts?q=internet 

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 

GET /db 

Returns default index file or serves ./public directory

GET / 

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.

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

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

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

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

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

You can load remote schemas.

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

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

// index.jsmodule.exports=function(){vardata={users: []}// Create 1000 usersfor(vari=0;i<1000;i++){data.users.push({id: i,name: 'user'+i})}returndata}

$ json-server index.js

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

There's many way to set up SSL in development. One simple way though is to use hotel.

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

{"/api/": "/", "/blog/:resource/:id/show": "/:resource/:id", "/blog/:category": "/posts?category=:category" }

Start JSON Server with --routes option.

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

Now you can access resources using additional routes.

/api/posts # → /posts /api/posts/1 # → /posts/1 /blog/posts/1/show # → /posts/1 /blog/javascript # → /posts?category=javascript

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

// hello.jsmodule.exports=function(req,res,next){res.header('X-Hello','World')next()}

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

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: "0.0.0.0"] --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"] --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.

{"port": 3000 }

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

$ npm install json-server --save-dev

// server.jsvarjsonServer=require('json-server')varserver=jsonServer.create()varrouter=jsonServer.router('db.json')varmiddlewares=jsonServer.defaults()server.use(middlewares)server.use(router)server.listen(3000,function(){console.log('JSON Server is running')})

$ 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:

varpath=require('path')varrouter=jsonServer.router(path.join(__dirname,'db.json'))

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

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

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

varjsonServer=require('json-server')varserver=jsonServer.create()varrouter=jsonServer.router('db.json')varmiddlewares=jsonServer.defaults()// Set default middlewares (logger, static, cors and no-cache)server.use(middlewares)// Add custom routes before JSON Server routerserver.get('/echo',function(req,res){res.jsonp(req.query)})// To handle POST, PUT and PATCH you need to use a body-parser// You can use the one used by JSON Serverserver.use(jsonServer.bodyParser)server.use(function(req,res,next){if(req.method==='POST'){req.body.createdAt=Date.now()}// Continue to JSON Server routernext()})// Use default routerserver.use(router)server.listen(3000,function(){console.log('JSON Server is running')})

varjsonServer=require('json-server')varserver=jsonServer.create()varrouter=jsonServer.router('db.json')varmiddlewares=jsonServer.defaults()server.use(middlewares)server.use(function(req,res,next){if(isAuthorized(req)){// add your authorization logic herenext()// continue to JSON Server router}else{res.sendStatus(401)}})server.use(router)server.listen(3000,function(){console.log('JSON Server is running')})

To modify responses, overwrite router.render method:

// In this example, returned resources will be wrapped in a body propertyrouter.render=function(req,res){res.jsonp({body: res.locals.data})}

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

// Add this before server.use(router)server.use(jsonServer.rewriter({'/api/': '/','/blog/:resource/:id/show': '/:resource/:id'}))

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

server.use('/api',router)

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

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

• Node Module Of The Week - json-server
• Mock up your REST API with 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

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

MIT - Typicode