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