json-server 0.17.4 → 1.0.0-alpha.10

package/README.md

@@ -1,633 +1,159 @@
-# JSON Server [![Node.js CI](https://github.com/typicode/json-server/actions/workflows/node.js.yml/badge.svg?branch=master)](https://github.com/typicode/json-server/actions/workflows/node.js.yml)
+> [!IMPORTANT]
+> Viewing alpha v1 documentation – usable but expect breaking changes. For stable version, see [here](https://github.com/typicode/json-server/tree/v0)
 
-Get a full fake REST API with __zero coding__ in __less than 30 seconds__ (seriously)
+# json-server
 
-Created with <3 for front-end developers who need a quick back-end for prototyping and mocking.
+[![Node.js CI](https://github.com/typicode/json-server/actions/workflows/node.js.yml/badge.svg)](https://github.com/typicode/json-server/actions/workflows/node.js.yml)
 
-* [Egghead.io free video tutorial - Creating demo APIs with json-server](https://egghead.io/lessons/nodejs-creating-demo-apis-with-json-server)
-* [JSONPlaceholder - Live running version](https://jsonplaceholder.typicode.com)
-* [__My JSON Server__ - no installation required, use your own data](https://my-json-server.typicode.com)
+## Install
 
-See also:
-* :dog: [husky - Git hooks made easy](https://github.com/typicode/husky)
-* :owl: [lowdb - local JSON database](https://github.com/typicode/lowdb)
-* ✅ [xv - a beautifully simple and capable test runner](https://github.com/typicode/xv)
-
-<p>&nbsp;</p>
-
-<h2 align="center">Gold sponsors 🥇</h2>
-
-<p>&nbsp;</p>
-
-<p align="center">
-  <a href="https://tryretool.com/?utm_source=sponsor&utm_campaign=typicode" target="_blank">
-    <img src="https://i.imgur.com/IBItATn.png" height="70px">
-  </a>
-</p>
-
-<p>&nbsp;</p>
-
-<p align="center">
-  <a href="https://mockend.com/" target="_blank">
-    <img src="https://jsonplaceholder.typicode.com/mockend.svg" height="70px">
-  </a>
-</p>
-
-<p>&nbsp;</p>
-
-<p>&nbsp;</p>
-
-<h2 align="center">Silver sponsors 🥈</h2>
-
-<p>&nbsp;</p>
-
-<p align="center">
-  <a href="https://cased.com" target="_blank">
-    <img src="https://user-images.githubusercontent.com/5502029/194441951-b7dca49d-efd6-496d-900b-288004717f11.png" height="55px">
-  </a>
-</p>
-
-<p>&nbsp;</p>
-
-<p>&nbsp;</p>
-
-[Become a sponsor and have your company logo here](https://github.com/users/typicode/sponsorship)
-
-## Sponsor
-
-__Please help me build OSS__ 👉 [GitHub Sponsors](https://github.com/sponsors/typicode) :heart:
-
-## Table of contents
-
-<!-- toc -->
-
-- [Getting started](#getting-started)
-- [Routes](#routes)
-  * [Plural routes](#plural-routes)
-  * [Singular routes](#singular-routes)
-  * [Filter](#filter)
-  * [Paginate](#paginate)
-  * [Sort](#sort)
-  * [Slice](#slice)
-  * [Operators](#operators)
-  * [Full-text search](#full-text-search)
-  * [Relationships](#relationships)
-  * [Database](#database)
-  * [Homepage](#homepage)
-- [Extras](#extras)
-  * [Static file server](#static-file-server)
-  * [Alternative port](#alternative-port)
-  * [Access from anywhere](#access-from-anywhere)
-  * [Remote schema](#remote-schema)
-  * [Generate random data](#generate-random-data)
-  * [HTTPS](#https)
-  * [Add custom routes](#add-custom-routes)
-  * [Add middlewares](#add-middlewares)
-  * [CLI usage](#cli-usage)
-  * [Module](#module)
-    + [Simple example](#simple-example)
-    + [Custom routes example](#custom-routes-example)
-    + [Access control example](#access-control-example)
-    + [Custom output example](#custom-output-example)
-    + [Rewriter example](#rewriter-example)
-    + [Mounting JSON Server on another endpoint example](#mounting-json-server-on-another-endpoint-example)
-    + [API](#api)
-  * [Deployment](#deployment)
-- [Links](#links)
-  * [Video](#video)
-  * [Articles](#articles)
-  * [Third-party tools](#third-party-tools)
-- [License](#license)
-
-<!-- tocstop -->
-
-## Getting started
-
-Install JSON Server 
-
-```
-npm install -g json-server
+```shell
+npm install json-server@alpha
 ```
 
-Create a `db.json` file with some data
+## Usage
+
+Create a `db.json` (or `db.json5`) file
 
 ```json
 {
   "posts": [
-    { "id": 1, "title": "json-server", "author": "typicode" }
+    { "id": "1", "title": "a title" },
+    { "id": "2", "title": "another title" }
   ],
   "comments": [
-    { "id": 1, "body": "some comment", "postId": 1 }
+    { "id": "1", "text": "a comment about post 1", "postId": "1" },
+    { "id": "2", "text": "another comment about post 1", "postId": "1" }
   ],
-  "profile": { "name": "typicode" }
+  "profile": {
+    "name": "typicode"
+  }
 }
 ```
 
-Start JSON Server
+Pass it to JSON Server CLI
 
-```bash
-json-server --watch db.json
+```shell
+$ json-server db.json
 ```
 
-Now if you go to [http://localhost:3000/posts/1](http://localhost:3000/posts/1), you'll get
+Get a REST API
 
-```json
-{ "id": 1, "title": "json-server", "author": "typicode" }
+```shell
+$ curl -H "Accept: application/json" -X GET http://localhost:3000/posts/1
+{
+  "id": "1",
+  "title": "a title"
+}
 ```
 
-Also when doing requests, it's good to know that:
+Run `json-server --help` for a list of options
 
-- If you make POST, PUT, PATCH or DELETE requests, changes will be automatically and safely saved to `db.json` using [lowdb](https://github.com/typicode/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. 
+|                                                                                    Sponsors                                                                                    |
+| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+|                         <a href="https://mockend.com/" target="_blank"><img src="https://jsonplaceholder.typicode.com/mockend.svg" height="70px"></a>                          |
+| <a href="https://www.storyblok.com/" target="_blank"><img src="https://github.com/typicode/json-server/assets/5502029/c6b10674-4ada-4616-91b8-59d30046b45a" height="40px"></a> |
 
-## Routes
-
-Based on the previous `db.json` file, here are all the default routes. You can also add [other routes](#add-custom-routes) using `--routes`.
+[Become a sponsor and have your company logo here](https://github.com/users/typicode/sponsorship)
 
-### Plural routes
+## Routes
 
 ```
 GET    /posts
-GET    /posts/1
+GET    /posts/:id
 POST   /posts
-PUT    /posts/1
-PATCH  /posts/1
-DELETE /posts/1
-```
-
-### Singular routes
-
-```
-GET    /profile
-POST   /profile
-PUT    /profile
-PATCH  /profile
+PUT    /posts/:id
+PATCH  /posts/:id
+DELETE /posts/:id
 ```
 
-### Filter
-
-Use `.` to access deep properties
-
 ```
-GET /posts?title=json-server&author=typicode
-GET /posts?id=1&id=2
-GET /comments?author.name=typicode
+GET   /profile
+PUT   /profile
+PATCH /profile
 ```
 
-### Paginate
+## Params
 
-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_
-
-### Sort
-
-Add `_sort` and `_order` (ascending order by default)
-
-```
-GET /posts?_sort=views&_order=asc
-GET /posts/1/comments?_sort=votes&_order=asc
-```
+### Conditions
 
-For multiple fields, use the following format:
+- ` ` → `==`
+- `lt` → `<`
+- `lte` → `<=`
+- `gt` → `>`
+- `gte` → `>=`
+- `ne` → `!=`
 
 ```
-GET /posts?_sort=user,views&_order=desc,asc
+GET /posts?views_gt=9000
 ```
 
-### Slice
+### Range
 
-Add `_start` and `_end` or `_limit` (an `X-Total-Count` header is included in the response)
+- `start`
+- `end`
+- `limit`
 
 ```
-GET /posts?_start=20&_end=30
-GET /posts/1/comments?_start=20&_end=30
-GET /posts/1/comments?_start=20&_limit=10
+GET /posts?_start=10&_end=20
+GET /posts?_start=10&_limit=10
 ```
 
-_Works exactly as [Array.slice](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) (i.e. `_start` is inclusive and `_end` exclusive)_
-
-### Operators
+### Paginate
 
-Add `_gte` or `_lte` for getting a range
+- `page`
+- `per_page` (default = 10)
 
 ```
-GET /posts?views_gte=10&views_lte=20
+GET /posts?_page=1&_per_page=25
 ```
 
-Add `_ne` to exclude a value
-
-```
-GET /posts?id_ne=1
-```
+### Sort
 
-Add `_like` to filter (RegExp supported)
+- `_sort=f1,f2`
 
 ```
-GET /posts?title_like=server
+GET /posts?_sort=id,-views
 ```
 
-### Full-text search
+### Nested and array fields
 
-Add `q`
+- `x.y.z...`
+- `x.y.z[i]...`
 
 ```
-GET /posts?q=internet
+GET /posts?author.name=foo
+GET /posts?author.email=foo
+GET /posts?names[0]=foo
 ```
 
-### Relationships
-
-To include children resources, add `_embed`
+### 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](#add-custom-routes) for more)
-
-```
-GET  /posts/1/comments
-POST /posts/1/comments
-```
-
-### Database
-
-```
-GET /db
-```
-
-### Homepage
-
-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.
-
-```bash
-mkdir public
-echo 'hello world' > public/index.html
-json-server db.json
-```
-
-```bash
-json-server db.json --static ./some-other-dir
+GET /comments?_embed=post
 ```
 
-### Alternative port
+## Delete
 
-You can start JSON Server on other ports with the `--port` flag:
-
-```bash
-$ json-server --watch db.json --port 3004
 ```
-
-### Access from anywhere
-
-You can access your fake API from anywhere using CORS and JSONP.
-
-### Remote schema
-
-You can load remote schemas.
-
-```bash
-$ json-server http://example.com/file.json
-$ json-server http://jsonplaceholder.typicode.com/db
-```
-
-### Generate random data
-
-Using JS instead of a JSON file, you can create data programmatically.
-
-```javascript
-// 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
-}
-```
-
-```bash
-$ json-server index.js
-```
-
-__Tip__ use modules like [Faker](https://github.com/faker-js/faker), [Casual](https://github.com/boo1ean/casual), [Chance](https://github.com/victorquinn/chancejs) or [JSON Schema Faker](https://github.com/json-schema-faker/json-schema-faker).
-
-### HTTPS
-
-There are many ways to set up SSL in development. One simple way is to use [hotel](https://github.com/typicode/hotel).
-
-### Add custom routes
-
-Create a `routes.json` file. Pay attention to start every route with `/`.
-
-```json
-{
-  "/api/*": "/$1",
-  "/:resource/:id/show": "/:resource/:id",
-  "/posts/:category": "/posts?category=:category",
-  "/articles?id=:id": "/posts/:id"
-}
-```
-
-Start JSON Server with `--routes` option.
-
-```bash
-json-server db.json --routes routes.json
-```
-
-Now you can access resources using additional routes.
-
-```sh
-/api/posts # → /posts
-/api/posts/1  # → /posts/1
-/posts/1/show # → /posts/1
-/posts/javascript # → /posts?category=javascript
-/articles?id=1 # → /posts/1
-```
-
-### Add middlewares
-
-You can add your middlewares from the CLI using `--middlewares` option:
-
-```js
-// hello.js
-module.exports = (req, res, next) => {
-  res.header('X-Hello', 'World')
-  next()
-}
-```
-
-```bash
-json-server db.json --middlewares ./hello.js
-json-server db.json --middlewares ./first.js ./second.js
-```
-
-### CLI usage
-
-```
-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: "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 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.
-
-```json
-{
-  "port": 3000
-}
+DELETE /posts/1
+DELETE /posts/1?_embed=comments
 ```
 
-### Module
+## Serving static files
 
-If you need to add authentication, validation, or __any behavior__, you can use the project as a module in combination with other Express middlewares.
+If you create a `./public` directory, JSON Serve will serve its content in addition to the REST API.
 
-#### Simple example
+You can also add custom directories using `-s/--static` option.
 
 ```sh
-$ npm install json-server --save-dev
+json-server -s ./static
+json-server -s ./static -s ./node_modules
 ```
 
-```js
-// 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')
-})
-```
-
-```sh
-$ 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:
-
-```js
-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()`.
-
-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.
-
-```js
-const jsonServer = require('json-server')
-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
-
-```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((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:
-
-```javascript
-// 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:
-
-
-```javascript
-// 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()`:
-
-```javascript
-// 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`.
-
-```javascript
-server.use('/api', router)
-```
-
-#### 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](#cli-usage))
-
-### Deployment
-
-You can deploy JSON Server. For example, [JSONPlaceholder](http://jsonplaceholder.typicode.com) is an online fake API powered by JSON Server and running on Heroku.
-
-## Links
-
-### Video
-
-* [Creating Demo APIs with json-server on egghead.io](https://egghead.io/lessons/nodejs-creating-demo-apis-with-json-server)
-
-### Articles
-
-* [Node Module Of The Week - json-server](http://nmotw.in/json-server/)
-* [ng-admin: Add an AngularJS admin GUI to any RESTful API](http://marmelab.com/blog/2014/09/15/easy-backend-for-your-restful-api.html)
-* [Fast prototyping using Restangular and Json-server](https://glebbahmutov.com/blog/fast-prototyping-restangular-and-json-server/)
-* [Create a Mock REST API in Seconds for Prototyping your Frontend](https://coligo.io/create-mock-rest-api-with-json-server/)
-* [No API? No Problem! Rapid Development via Mock APIs](https://medium.com/@housecor/rapid-development-via-mock-apis-e559087be066#.93d7w8oro)
-* [Zero Code REST With json-server](https://dzone.com/articles/zero-code-rest-with-json-server)
-
-### Third-party tools
-
-* [Grunt JSON Server](https://github.com/tfiwm/grunt-json-server)
-* [Docker JSON Server](https://github.com/clue/docker-json-server)
-* [JSON Server GUI](https://github.com/naholyr/json-server-gui)
-* [JSON file generator](https://github.com/dfsq/json-server-init)
-* [JSON Server extension](https://github.com/maty21/json-server-extension)
-
 ## License
 
-MIT
+This project uses the [Fair Source License](https://fair.io/). Note: Only organizations with 3+ users need to contribute a small amount through sponsorship [sponsor](https://github.com/sponsors/typicode) for usage. This license helps keep the project sustainable and healthy, benefiting everyone.
 
-[Supporters](https://thanks.typicode.com) ✨
+For more information, FAQs, and the rationale behind this, visit [https://fair.io/](https://fair.io/).