PhilliesGomideJSON Server with Relationships 
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:
- :dog: husky - Git hooks made easy
- :hotel: hotel - developer tool with local .localhost domain and https out of the box
- ⚛️ 🔧 react-lodash - lodash as React components
To all the amazing people who have answered the JSON Server survey, thanks so much <3 !
Sponsors
Table of contents
- Sponsorship
- Getting started
- Routes
- Extras
- Links
- License
Getting started
Install JSON Server
npm i json-server-relationshipCreate a db.json file with some data
{
"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.jsonNow 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.jsonusing lowdb. - Your request body JSON should be object enclosed, just like the GET output. (for example
{"name": "Foobar"}) - Id values are not mutable. Any
idvalue 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/jsonheader to use the JSON in the request body. Otherwise it will result in a 200 OK 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/1Singular routes
GET /profile
POST /profile
PUT /profile
PATCH /profileFilter
Use . to access deep properties
GET /posts?title=json-server&author=typicode
GET /posts?id=1&id=2
GET /comments?author.name=typicodePaginate
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=2010 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=ascFor multiple fields, use the following format:
GET /posts?sort=user,views&order=desc,ascSlice
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=10Works exactly as [Array.slice](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/GlobalObjects/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=20Add _ne to exclude a value
GET /posts?id_ne=1Add _like to filter (RegExp supported)
GET /posts?title_like=serverFull-text search
Add q
GET /posts?q=internetRelationships
To include children resources, add embed
GET /posts?embed=comments
GET /posts/1?embed=comments
GET /tags/1?embed=commentsTo include parent resource, add expand
GET /comments?expand=post
GET /comments/1?expand=post
GET /comments/1?expand=tagsTo get or create nested resources (by default one level, add custom routes for more)
GET /posts/1/comments
POST /posts/1/commentsTo include many to many relationships
GET /posts?include=tags
GET /posts/1?include=tags
GET /tags?include=posts
GET /tags/1?include=postsDatabase
GET /dbHomepage
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.
mkdir public
echo 'hello world' > public/index.html
json-server-relationship db.jsonjson-server-relationship db.json --static ./some-other-dirAlternative port
You can start JSON Server on other ports with the --port flag:
$ json-server-relationship --watch db.json --port 3004Access from anywhere
You can access your fake API from anywhere using CORS and JSONP.
Remote schema
You can load remote schemas.
$ json-server-relationship http://example.com/file.json
$ json-server-relationship http://jsonplaceholder.typicode.com/dbGenerate random data
Using JS instead of a JSON file, you can create data programmatically.
// index.js
module.exports = () => {
const data = { users: [] };
// Create 1000 users
for (let i = 0; i < 1000; i++) {
data.users.push({ id: i, name: `user${i}` });
}
return data;
};$ json-server-relationship index.jsTip use modules like Faker, Casual, Chance or JSON Schema Faker.
HTTPS
There's many way to set up SSL in development. One simple way though is to use hotel.
Add custom routes
Create a routes.json file. Pay attention to start every route with /.
{
"/api/*": "/$1",
"/:resource/:id/show": "/:resource/:id",
"/posts/:category": "/posts?category=:category",
"/articles\\?id=:id": "/posts/:id"
}Start JSON Server with --routes option.
json-server-relationship db.json --routes routes.jsonNow you can access resources using additional routes.
/api/posts # → /posts
/api/posts/1 # → /posts/1
/posts/1/show # → /posts/1
/posts/javascript # → /posts?category=javascript
/articles?id=1 # → /posts/1Add middlewares
You can add your middlewares from the CLI using --middlewares option:
// hello.js
module.exports = (req, res, next) => {
res.header("X-Hello", "World");
next();
};json-server-relationship db.json --middlewares ./hello.js
json-server-relationship db.json --middlewares ./first.js ./second.jsCLI usage
json-server-relationship [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-relationship db.json
json-server-relationship file.js
json-server-relationship http://example.com/db.json
https://github.com/PhilliesGomide/json-server-relationship/You can also set options in a json-server.json configuration file.
{
"port": 3000
}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
$ npm install json-server-relationship --save-dev// server.js
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");
});$ node server.jsThe 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:
const path = require("path");
const router = 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.
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.
const jsonServer = require("json-server-relationship");
const server = jsonServer.create();
const router = jsonServer.router("db.json");
const middlewares = jsonServer.defaults();
// Set default middlewares (logger, static, cors and no-cache)
server.use(middlewares);
// Add custom routes before JSON Server router
server.get("/echo", (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 Server
server.use(jsonServer.bodyParser);
server.use((req, res, next) => {
if (req.method === "POST") {
req.body.createdAt = Date.now();
}
// Continue to JSON Server router
next();
});
// Use default router
server.use(router);
server.listen(3000, () => {
console.log("JSON Server is running");
});Access control example
const jsonServer = require("json-server-relationship");
const server = jsonServer.create();
const router = jsonServer.router("db.json");
const middlewares = jsonServer.defaults();
server.use(middlewares);
server.use((req, res, next) => {
if (isAuthorized(req)) {
// add your authorization logic here
next(); // continue to JSON Server router
} else {
res.sendStatus(401);
}
});
server.use(router);
server.listen(3000, () => {
console.log("JSON Server is running");
});Custom output example
To modify responses, overwrite router.render method:
// In this example, returned resources will be wrapped in a body property
router.render = (req, res) => {
res.jsonp({
body: res.locals.data
});
};You can set your own status code for the response:
// In this example we simulate a server side error response
router.render = (req, res) => {
res.status(500).jsonp({
error: "error message here"
});
};Rewriter example
To add rewrite rules, use jsonServer.rewriter():
// Add this before server.use(router)
server.use(
jsonServer.rewriter({
"/api/*": "/$1",
"/blog/:resource/:id/show": "/:resource/:id"
})
);Mounting JSON Server on another endpoint example
Alternatively, you can also mount the router on /api.
server.use("/api", router);API
jsonServer.create()
Returns an Express server.
jsonServer.defaults([options])
Returns middlewares used by JSON Server.
- options
staticpath to static filesloggerenable logger middleware (default: true)bodyParserenable body-parser middleware (default: true)noCorsdisable CORS (default: false)readOnlyaccept only GET requests (default: false)
jsonServer.router([path|object])
Returns JSON Server router.
Deployment
You can deploy JSON Server. For example, JSONPlaceholder is an online fake API powered by JSON Server and running on Heroku.
Links
Video
Articles
- 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
- Zero Code REST With json-server
Third-party tools
License
MIT
Patreon - Supporters ✨