How to bootstrap your project with JSON Server
Tags: tutorial, bootstrap, json
Published: 2020-01-23 17:26:34

---
title: How to bootstrap your project with JSON Server
published: true
date: 2020-01-21 19:00:10 UTC
tags: tutorial, bootstrap, json
canonical_url: https://blog.logrocket.com/how-to-bootstrap-your-project-with-json-server/
cover_image: https://thepracticaldev.s3.amazonaws.com/i/nnrhvzo7npnhj6460uvw.png
---
**Written by [Michiel Mulders](https://blog.logrocket.com/author/michielmulders/)**✏️

JSON Server enables frontend developers to quickly spin up a fake REST API to validate how an app’s interface reacts when receiving data from the backend. This is especially useful when the required backend routes have not been finished yet.

At a high level, there’s not much to it: all you need to do is create a JSON file that defines endpoints and sample data — no further configuration required. In fact, you can bootstrap a fake [REST API](https://blog.logrocket.com/how-to-secure-a-rest-api-using-jwt-7efd83e71432/) in under five minutes.

In this tutorial, we’ll demonstrate:

- How to bootstrap a simple REST API with JSON Server
- How to send `GET`, `POST`, and `PUT` requests
- How to send advanced requests with filtering and sorting parameters
- How to define relationships between segments of data

Let’s dig in!

[![LogRocket Free Trial Banner](https://i0.wp.com/blog.logrocket.com/wp-content/uploads/2017/03/f760c-1gpjapknnuyhu8esa3z0jga.png?resize=1200%2C280&ssl=1)](https://logrocket.com/signup/)

## Installing JSON Server

Before we can send any request, we need to install JSON Server. Preferably, we’d use npm to install the `json-server` package globally.

```jsx
npm install -g json-server
```

Now that JSON Server has been globally installed, we can create our first server configuration.

## Understanding the JSON Server configuration

The next step is to create our first `db.json` file, which holds the JSON configuration for the fake REST API. Below is a sample configuration, which includes three endpoints: authors, books, and library.

```jsx
{
 "authors": [
   { "id": 1, "name": "Michiel Mulders", "genre": "fiction" }
 ],
 "books": [
   { "id": 1, "title": "some title", "authorId": 1 }
 ],
 "library": { "name": "City library" }
}
```

### Plural endpoints

Note how we define endpoints: every endpoint with a plural name contains an array of objects, and each object represents a database record for that endpoint. For example, the `authors` endpoint will return one author object with `id: 1` and name equal to Michiel Mulders.

For plural endpoints, JSON Server generates the following routes:

- `GET /authors` returns all authors
- `GET /authors/1` returns author with ID 1
- `POST /authors` creates a new author in the database
- `PUT /authors/1` updates the entire author object for ID 1
- `PATCH /authors/1` updates specific fields for the author object with ID 1
- `DELETE /authors/1` deletes a specific author object

### Singular endpoints

The JSON configuration shows a singular endpoint library. When you define an endpoint in its singular form, it can only return one object. It’s not possible to define an array.

As for the generated routes for a singular endpoint, `GET/POST/PUT/PATCH /library` is basic set of operations available for the object, but it is not able to delete the object.

Now we understand the possible routes JSON Server generates. Let’s start our first server!

## Starting your first JSON Server

To start the server and serve the above endpoints, we’ll use the `json-server` command in the command line. We’ll tell the `json-server` command to watch our `db.json` configuration file.

```jsx
json-server --watch db.json
```

You can verify that your server is running by sending a `GET` request to [`http://localhost:3000/authors/1`](http://localhost:3000/authors/1). If it returns a result, you are ready to explore other endpoints.

### How to send a `POST` request

We can send a `POST` request via [Postman](https://www.getpostman.com/) or [curl](https://gist.github.com/subfuzion/08c5d85437d5d4f00e58). Don’t forget to pass the correct headers for the request. Since we’re dealing with a JSON API, we need to send the `Content-Type: application/json` header.

A `POST` request can simply be sent via a request body. The body below will create a new author object in our database. Don’t forget to send the request to the correct URL: [`http://localhost:3000/authors`](http://localhost:3000/authors).

```jsx
{
    "name": "Gregory Salis",
    "genre": "nonfiction"
}
```

As you can see, the request body doesn’t have to pass an ID. JSON Server will automatically create a new ID for your author object.

### How to send a `PUT` request

Sending a `PUT` request is very similar to sending a `POST` request. First we must specify the ID of the object that needs to be updated. Let’s update the original author object with ID 1 using the URL [`http://localhost:3000/authors/1`](http://localhost:3000/authors/1).

The `PUT` request has to modify the genre from fiction to nonfiction. Therefore, the request body will look like this:

```jsx
{
    "name": "Michiel Mulders",
    "genre": "nonfiction"
}
```

Besides sending simple `GET`, `POST`, and `PUT` requests, JSON Server allows for more advanced requests such as filtering, sorting, and searching.

## Advanced JSON Server requests

To enrich its functionality, JSON Server comes with searching, sorting, and filtering options.

### Sorting

Data can be sorted through the `_sort` option. Let’s say we want to sort authors by genre. The sort request will look like this:

```jsx
http://localhost:3000/authors?_sort=genre
```

However, the order of the sorting result needs to be switched from `asc` to `desc`. The `_order` option allows us to change the sorting from ascending to descending.

```jsx
http://localhost:3000/authors?_sort=genre&_order=desc
```

### Filtering

We can achieve data filtering by defining the field and required value we want to filter for. The example link below would retrieve all nonfiction authors. The request defines the genre field and the required value `nonfiction`.

```jsx
http://localhost:3000/authors?genre=nonfiction
```

Also, JSON Server allows us to combine filters. Now the request should retrieve all nonfiction books by the author Michiel Mulders. The below request defines two fields which are chained by the ampersand (&) character.

```jsx
http://localhost:3000/authors?genre=nonfiction&name=Michiel%20Mulders
```

Note: The space between Michiel and Mulders is encoded by `%20`. This is a common practice for encoding URLs. Lastly, `json-server` provides several searching possibilities.

### Searching

Last but not least, searching can be performed in various ways. The full text search option helps with finding a specific value. This approach is easiest when looking for values. Here, the request should find all authors that include “Michiel” in their name.

```jsx
http://localhost:3000/authors?genre_like=michiel
```

Moreover, JSON Server helps with finding values for specific fields. For example, the request should return all matching records that include “Michiel” in the genre field. When investigating the `db.json` file, this request should return an empty response because “Michiel” does not appear in the genre field.

We can filter by appending the `_like` operator to the field we want to search for. Now, the request includes a `genre_like` option.

```jsx
http://localhost:3000/authors?genre_like=michiel
```

Also, the `_like` operator supports [regular expression](https://www.regular-expressions.info/) queries. The following query should retrieve all genres that start with the `non` keyword. Notice the asterisk symbol appended to the `genre_like` option — that’s part of the regex.

```jsx
http://localhost:3000/authors?genre_like=non*
```

More operators, such as `_gte`, `_lte`, and `_ne`, can be found in the [JSON Server documentation](https://github.com/typicode/json-server#operators).

## Understanding relationships with JSON Server

A fake JSON server that doesn’t come with the ability to define relationships between endpoints would be quite useless. Most data requires the ability to define data relationships. Let’s discuss how `json-server` allows for the definition of relationships between data points.

First, remember the `db.json` configuration we started with:

```jsx
{
 "authors": [
   { "id": 1, "name": "Michiel Mulders", "genre": "fiction" }
 ],
 "books": [
   { "id": 1, "title": "some title", "authorId": 1 }
 ],
 "library": { "name": "City library" }
}
```

Now notice the `authorId` field for the `books` endpoint. By using the singular form of another data entity in our database, we can link it by appending the `id` keyword. Here we’ve linked a book with the title “some title” to the author with ID 1.

Furthermore, this allows us to query for all books written by Michiel Mulders, the author with the ID equal to 1. The query requires the addition of the `books` keyword to specify the retrieval of all books for this author.

```jsx
http://localhost:3000/authors/1/books
```

Again, we further filter for those endpoints, such as the following request.

```jsx
http://localhost:3000/authors/1/books?title_like=some
```

But what if we want to include the parent resource (authors)?

### Including the parent resource

Moreover, `json-server` allows us to include the parent resource through the _`_embed`_ option. The request will look slightly different now because we are starting from the `authors` endpoint and asking to embed all books for the author with an ID equal to 1.

```jsx
http://localhost:3000/authors/1?_embed=books
```

The result looks like this when sending the above `GET` request:

```jsx
{

    id: 1,
    name: "Michiel Mulders",
    genre: "fiction",
    books:
    [
                  {
                           id: 1,
                       title: "some title",
                       authorId: 1
                   }
    ]
}
```

## 4 useful tips for using JSON Server

To wrap up our tutorial, we’ll review some common best practices to help you get the most out of `json-server`.

Besides generating routes, `json-server` ships with many other interesting features that can be useful for you. Let’s explore four of the most interesting features.

### 1. Database snapshotting

Imagine you’ve updated and created many new objects and you don’t want to lose your progress. You can hit `s + enter` on your keyboard to take a snapshot of the current database state.

The snapshot is saved in the same folder and the name will be appended with a unix timestamp, producing something like this: `db-1578083664783.json`.

### 2. Add custom routes

The name “custom routes” is actually quite misleading. `json-server` allows you to create aliases for existing routes.

Let’s say your frontend relies on an API that is served from the root path starting with `/api/v1`. Since `json-server` does not include this prefix, we have to create a custom route. We’ll create a `routes.json` file to tell `json-server` which mappings to establish. The below example maps all `json-server` routes to the required prefix `/api/v1`.

```jsx
{
  "/api/*": "/$1"
}
```

Next, we can also create shorter paths for long URLs.

```jsx
{
  "/api/*": "/$1",
  "/:resource/:id/show": "/:resource/:id"
}
```

To tell `json-server` to use these aliases, pass the `--routes `option to the start command.

```jsx
json-server --watch db.json --routes routes.json
```

### 3. Change port

By default, `json-server` serves its API on port 3000. We can change the port with the `--port` option.

```jsx
json-server --watch db.json --port 5000
```

### 4. Custom middleware

Lastly, `json-server` allows you to define custom middleware. For example, let’s create a `headers.js` file that contains a small snippet of code to add an extra custom header to the request.

`json-server` follows the same pattern that Express.js uses for requests: `req`, `res`, and `next`. Therefore, you can modify the data for a request or add an extra header to the `res` object, like this:

```jsx
module.exports = (req, res, next) => {
  res.header('X-Hello', 'World')
  next()
}
```

To serve `json-server` with the above middleware, pass the `--middlewares` option.

```jsx
json-server --watch db.json --middlewares headers.js
```

## Conclusion

Before you start running wild with your mock APIs, let’s quickly recap what we learned.

JSON Server focuses on simplicity and speed of use. It allows any frontend developer to spin up a fake REST API in under five minutes.

Furthermore, it’s easy to add relationships between data. Simply adding the `id` keyword enables you to link any data. `json-server` allows you to filter, sort, and query for data just like a regular API.

Next time you’re validating frontend components, consider using `json-server` to quickly bootstrap a JSON REST API. When your project requires special components, `json-server` allows for customizations through middleware.

To see what else you can do with JSON Server, check out the [official documentation](https://github.com/typicode/json-server#table-of-contents).

* * * 
## Plug: [LogRocket](https://logrocket.com/signup/), a DVR for web apps
 
![LogRocket Dashboard Free Trial Banner](https://i2.wp.com/blog.logrocket.com/wp-content/uploads/2017/03/1d0cd-1s_rmyo6nbrasp-xtvbaxfg.png?resize=1200%2C677&ssl=1)
 
[LogRocket](https://logrocket.com/signup/) is a frontend logging tool that lets you replay problems as if they happened in your own browser. Instead of guessing why errors happen, or asking users for screenshots and log dumps, LogRocket lets you replay the session to quickly understand what went wrong. It works perfectly with any app, regardless of framework, and has plugins to log additional context from Redux, Vuex, and @ngrx/store.
 
In addition to logging Redux actions and state, LogRocket records console logs, JavaScript errors, stacktraces, network requests/responses with headers + bodies, browser metadata, and custom logs. It also instruments the DOM to record the HTML and CSS on the page, recreating pixel-perfect videos of even the most complex single-page apps.
 
[Try it for free](https://logrocket.com/signup/).
* * *

The post [How to bootstrap your project with JSON Server](https://blog.logrocket.com/how-to-bootstrap-your-project-with-json-server/) appeared first on [LogRocket Blog](https://blog.logrocket.com).