@discovery-solutions/json-server

JSON Server

This library allows you to create multiple API servers with minimum amount of code or setup, using a JSON configuration.

The generated API can handle simple CRUD of entities to authentication, and much more. Check the documentation bellow.

To understand the endpoints generated by the API, check this section.

CHECK COMPLETE EXAMPLE

Installation

Run the following command:

npm install --save @discovery-solutions/json-server

If you want to use features like connection with MongoDB or JWT for authentication, you should install those libraries:

npm install --save mongodb
npm install --save jsonwebtoken

Basic Setup

import Server from "@discovery-solutions/json-server";

const server = new Server({
  name: "my-server",
  config: {
    port: 3500,
    type: "rest",
    format: "json",
  },
  database: {
    type: "custom",
    key: "my-db-1",
    name: "my-custom-db"
  },
  entities: [{
    name: "user",
    alias: "User",
    fields: {
      name: {
        type: "string",
        required: true
      },
      email: {
        type: "string",
        required: true
      },
      password: {
        type: "string",
        required: true
      },
      phone: "string",
      birthdate: "date",
      avatar: "image"
    }
  }]
});

server.run();

Or you could also, save this into a JSON file (it must be called server.json), and run the following command to start the server:

npx json-server

The file should look like this:

{
  "name": "my-server",
  "config": {
    "port": 3500,
    "type": "rest",
    "format": "json"
  },
  "database": {
    "type": "custom",
    "key": "my-db-1",
    "name": "my-custom-db"
  },
  "entities": [
    {
      "name": "user",
      "alias": "User",
      "fields": {
        "name": {
          "type": "string",
          "required": true
        },
        "email": {
          "type": "string",
          "required": true
        },
        "password": {
          "type": "string",
          "required": true
        },
        "phone": "string",
        "birthdate": "date",
        "avatar": "image"
      }
    }
  ]
}

---

Parameters

Parameter Key	Description	Required	Default Value
name	The server project name	true
label	Label displayed at API Docs	false	value of name
cors	CORS Setup	false	false
config	Setup of the servers	true
database	Database setup	false	native
entities	Entities for CRUD features	true

name

The simplest of all the parameters, just an identifyer for your project. This should be an string, like the example below:

const server = new Server({
  name: "my-server",
  // ...
});

label

This is a label to display at API Autogenerated Docs.

const server = new Server({
  name: "my-server",
  label: "My Server Project"
  // ...
});

cors

This is flag to allow CORS.

const server = new Server({
  // ...
  cors: true,
  // ...
});

config

This could a simple object for one server, or an array of objects for multiple servers configuration.

Key	Description	Type or Options	Required
port	number of the port the server should run	number	true
database	the database key the server should use	string	true
format	format of the responses	json, csv
type	type of the server	rest, socket
request	settings for requests	object

Complete example:

const server = new Server({
  // ...
  config: {
    port: 3500,
    type: "rest",
    format: "json",
    database: "my-db-1",
    request: {
      limit: 10,
    },
  }
});

Multiple servers example

const server = new Server({
  // ...
  config: [{
    port: 3501,
    type: "rest",
    database: "my-db-1",
    format: "json",
  }, {
    port: 3501,
    type: "socket",
    database: "my-db-2",
    format: "csv",
  }]
});

Database

The project supports 2 databases types: MongoDB and Local File Storage.

To use MongoDB, you need to install it:

npm install --save mongodb

The basic setup is simple:

Key	Description	Type or Options	Required
type	type of database connection	mongo or custom	false
key	a database key/identifyer	string	false
name	the database name	string	false

Custom Example

const server = new Server({
  // ...
  database: {
    type: "custom",
    key: "my-db",
    name: "database-name",
  }
});

Mongo Example

const server = new Server({
  // ...
  database: {
    type: "mongo",
    key: "my-db",
    name: "database-name",
    uri: "mongodb+srv://...",
  }
});

Multiple Databases Example

const server = new Server({
  // ...
  database: [{
    type: "custom",
    key: "my-db-1",
    name: "my-custom-db"
  }, {
    type: "mongo",
    key: "my-db-2",
    name: "my-mongo-db",
    uri: "mongodb+srv://...",
  }],
});

Entities

Entities are like models in a project. If you're creating a blog, this is the place where you should declare the Post, User, Comments, Likes, Tags, and other entities.

Key	Description	Type or Options	Required
name	entity name	string	true
alias	entity alias for visualization purposes	string	true
fields	object with the entity fields	object	true
auth	authentication settings	object	false
permissions	public access settings	object	false

fields

The configuration is a key/value system, where the value should be the data type of the content, or a object with more settings.

The settings can look like this:

Key	Description	Type or Options	Required
type	type of the content	string, number, boolean, object, date, image, file	true
required	field is a required for entity	boolean	false
secure	field should not be returned with responses	boolean	false

Check the below example:

const server = new Server({
  entities: [{
    name: "user",
    alias: "User",
    fields: {
      name: "string",
      email: {
        type: "string",
        required: true,
        secure: true
      }
    }
  }]
});

auth

The default value is false, so if you set this field in your entity, it means this is should be an authenticated entity.

Key	Description	Type or Options	Required
fields	list of the fields used for authentication	array	true
type	authentication type	jwt or token	false
permission	settings for access permission	object	false

Check a complete example:

const server = new Server({
  entities: [{
    name: "user",
    alias: "User",
    fields: {
      name: "string",
      email: "string",
      password: "string",
    },
    auth: {
      type: "jwt",
      fields: ["login", "password"],
      permission: {
        "*": {
          insert: false,
          update: false,
          delete: false,
          list: true,
          get: true,
        },
        "post": {
          insert: true,
          update: true,
          delete: false,
          list: true,
          get: true,
        }
      }
    }
  }]
});

Custom Routes

You can easily add custom routes using the server object returned by the JSONServer Class, in a ExpressJS like manner.

const server = new Server({ ... });

server.routes.get("/my/endpoint", (req, res) => {
  res.json({ message: "It's working "})
})

Roadmap

Present features:

• [x] CRUD routes
  • [x] Insert
  • [x] List/Get
  • [x] Update
  • [x] Delete
  • [x] Bulk insert
• [x] Authentication
  • [x] JWT
  • [x] Simple Token
  • [x] Authentication routes
  • [x] Authorization handler
• [x] Create tests for features
• [x] Interceptor to add custom requests
• [x] Add logger for request and API transactions
• [x] Full search for all entities
• [x] Finish Docs
• [x] Create Autogenerated Documentation for API Endpoints
• [ ] File upload
• [ ] Databases
  • [x] In-Memory DB
  • [ ] PostgreSQL
  • [x] MongoDB
  • [ ] MySQL

Future features:

• [ ] Blog setup (?)
• [ ] Chat setup (?)
• [ ] Ecommerce Setup (?)
• [ ] Bulk actions
  • [x] Bulk insert
  • [ ] Bulk update
  • [ ] Bulk delete