nss-json-server

NSS JSON Server

This package will pull in useful mixins created by us and other developers. Documentation and options are simplified for instruction of beginners.

Mixins:

• JWT authentication middleware for JSON Server published by Jeremy Bensimon at Json Server with Auth
• Nested resource expansion for multiple levels of related resources

Getting started

Package Install

# NPM
npm i -g nss-json-server

# Yarn
yarn global add nss-json-server

Create a db.json file with a users collection :

{
  "users": []
}

Alias Setup

Open your bash or zsh initialization file and add the following alias.

alias js="nss-json-server -X 7h -p 5050 -w"

Running your API

Run with following command:

js db.json

It exposes and works the same for all JSON Server flags.

Authentication flow

JSON Server Auth adds a simple JWT based authentication flow.

Register

• POST /register

email and password are required in the request body :

POST /register
{
  "email": "admina@gmail.com",
  "password": "bestPassw0rd"
}

The response contains the JWT access token, user id and username (if exists):

201 Created
{
  "accessToken": "xxx.xxx.xxx",
  "user": {
    "id": 1,
    "username": "xxxxxxxx"
  }
}

Any other property can be added to the request body without being validated:

POST /register
{
  "email": "admina@gmail.com",
  "password": "bestPassw0rd",
  "username": "admina",
  "firstname": "Admina",
  "lastname": "Straytor",
  "age": 32
}

Login

• POST /login

email and password are required:

POST /login
{
  "email": "admina@gmail.com",
  "password": "bestPassw0rd"
}

The response contains the JWT access token:

200 OK
{
  "accessToken": "xxx.xxx.xxx",
  "user": {
    "id": 1,
    "username": "xxxxxxxx"
  }
}

Creating Owned Resources

If any resource has been guarded with an ownership level route:

Permission	Description
600	User must own the resource to write or read the resource.
640	User must own the resource to write the resource. User must be logged to read the resource.
644	User must own the resource to write the resource. Everyone can read the resource.

Then when you make a request with the POST or PUT method, and there is an authorization header, then the userId will be automatically added to the request body.

Example

fetch("http://localhost:5050/posts", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        Accept: "application/json",
        Authorization: "Bearer xxxxxx.xx.xxxxx"
    },
    body: JSON.stringify({
        url: "https://media.giphy.com/media/eHWWKfSp0VZ1V87Ixj/giphy.gif",
        image: null,
        timestamp: Date.now()
    })
})

Example response:

{
  "url": "https://media.giphy.com/media/eHWWKfSp0VZ1V87Ixj/giphy.gif",
  "image": null,
  "timestamp": 1575211182251,
  "userId": 4,
  "id": 8
}

Nested Resource Expansion

NSS JSON Server enhances JSON Server's _expand parameter to support multiple levels of resource embedding.

Basic Usage

The standard JSON Server _expand parameter allows you to embed a related resource based on a foreign key:

GET /people/1?_expand=city

Response:

{
  "id": 1,
  "name": "John Smith",
  "cityId": 4,
  "city": {
    "id": 4,
    "name": "Pittsburgh",
    "stateId": 22
  }
}

Nested Expansion

With the nested expansion enhancement, you can now expand multiple levels deep using dot notation:

GET /people/1?_expand=city.state

Response:

{
  "id": 1,
  "name": "John Smith",
  "cityId": 4,
  "city": {
    "id": 4,
    "name": "Pittsburgh",
    "stateId": 22,
    "state": {
      "id": 22,
      "name": "Pennsylvania"
    }
  }
}

For more details and advanced usage, see the Nested Expansion Documentation.

For Local Development

1. Clone repo
2. npm i
3. Create a routes.json and db.json
4. Add the following to your routes.json

Sample routes.json

{
    "/users*": "/640/users$1",
    "/posts*": "/640/posts$1"
}

Starting the Dev Server

1. npm run build
2. node dist/bin.js -w db.json -p 5050 -X 7h -r routes.json

Basic Requests

Using Postman, or your favorite HTTP request client, create the following requests.

• http://localhost:5050/register

  // Body (raw JSON)
  {
      "email": "admina@gmail.com",
      "password": "Admin8*",
      "name": "Admina Straytor",
      "username": "admin",
      "location": "Nashville, TN",
      "avatar": ""
  }

  • Method - POST
  • Content-Type header - application/json
• http://localhost:5050/posts

  // Body (raw JSON)
  {
      "url": "https://media.giphy.com/media/eHWWKfSp0VZ1V87Ixj/giphy.gif",
      "image": null,
      "timestamp": 1575211182251
  }

  • Method - POST
  • Authorization header - Use token from registration response
  • Content-Type header - application/json
  • Accept header - application/json