REST-Docs

RESTful HTTP client library + Docs to test your API REST. Supports for PostgreSQL, MySQL, MariaDB, MSSQL and SQLite3.

Table of contents

• Install
• Install Database Library
• Usage
• Usage with .env file
• Result
• Test API
• Methods
• Migrations
• Examples
• Author
• License

Install

npm i rest-docs --save

Install Database Library

• MSSQL

npm i mssql --save

• MySQL and MariaDB

npm i mysql --save

• PostgreSQL

npm i pg --save

• SQLite3

npm i sqlite3 --save

Usage

// server.js
const rest_docs = require('rest-docs');
var rest = new rest_docs();

rest.startServer({
  ip: '127.0.0.1', //<-- YOUR_SERVER_IP
  port: '8080', //<-- YOUR_SERVER_PORT
  compression: 'gzip' //<-- YOUR_COMPRESSION_STRATEGY
})

rest.startDBServer('mysql', {
  host: 'localhost', //<-- YOUR_DATABASE_HOST
  port: 3306, //<-- YOUR_DATABASE_PORT
  user: 'root', //<-- YOUR_DATABASE_USER
  password: '', //<-- YOUR_DATABASE_PASSWORD
  database: 'medic', //<-- YOUR_DATABASE_NAME
  timezone: '+00:00' //<-- YOUR_DATABASE_TIMEZONE
});

const api_config = {
  base: '/api',
  pages: {
    docs: true, //<-- Expose PAGE: /{{base}}/docs
    monitor: true //<-- Expose PAGE: /{{base}}/monitor
  },
  routes: {
    tb: [
      {      
        table: 'doctors', //<-- YOUR_TABLE_NAME
        event: 'DOCTOR', //<-- YOUR_EVENT_NAME 
        methods: ['GET', 'POST', 'PUT', 'DELETE'], //<-- YOUR_METHODS
        //Used only by methods 'POST' and 'PUT'
        columns: [
            {name: 'id', primary: true},
            {name: 'name'},
            {name: 'specialty'},
            {name: 'address'},
            {name: 'photo'}
        ]
      }
    ]  
  }
}

rest.buildRoutes(api_config)

Run

node server.js
# PAGES: {
#   api: 'http://127.0.0.1:8080/api',
#   docs: 'http://127.0.0.1:8080/api/docs',
#   monitor: 'http://127.0.0.1:8080/api/monitor'    
# }
# App listening at http://127.0.0.1:8080

Usage with .env file

npm i dotenv --save

// .env
NODE_ENV=development

IP=localhost
PORT=8000
COMPRESSION=gzip

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=
DB_DATABASE=medic

API_KEY=65856b68541470a4ad95e7fe8b6bbb40

// server.js
const rest_docs = require('rest-docs');
var rest = new rest_docs();

rest.startServer()
rest.startDBServer();

const api_config = {
  base: '/api',
  table: {
    created_date: 'created',
    modified_date: 'modified',
    active: 'deleted'
  },
  routes: {
    tb: [
      {      
        table: 'doctors', //<-- YOUR_TABLE_NAME
        event: 'DOCTOR', //<-- YOUR_EVENT_NAME 
        methods: ['GET', 'POST', 'PUT', 'DELETE'], //<-- YOUR_METHODS
        //Used only by methods 'POST' and 'PUT'
        columns: [
            {name: 'id', primary: true},
            {name: 'name'},
            {name: 'specialty'},
            {name: 'address'},
            {name: 'photo'}
        ]
      }
    ]
  }  
}

rest.buildRoutes(api_config)

Run

node server.js
# PAGES: {
#   api: 'http://localhost:8000/api',
#   docs: 'http://localhost:8000/api/docs',
#   monitor: 'http://localhost:8000/api/monitor'    
# }
# App listening at http://localhost:8000

Result

• GET /api/docs

Test API

• GET /api/doctors

• GET /api/doctors/:id

• POST /api/doctors

• PUT /api/doctors/:id

• DELETE /api/doctors/:id

Pages

• Docs /api/docs

• Monitor /api/monitor

Methods

• startServer(SERVER_CONFIG)

The SERVER_CONFIG represents the connection to the server.

Constant	Default	Description
ip	'localhost'	Server ip
port	8000	Server port
compression	''	Compression strategy

Example:

// SERVER_CONFIG
{
  ip: {YOUR_SERVER_IP},
  port: {YOUR_SERVER_PORT},
  compression: {YOUR_COMPRESSION_STRATEGY}
}

• startDBServer(CLIENT, CONNECTION_CONFIG)

The CLIENT parameter is required and determines which client adapter will be used with the library. By default: myslq.

Database	CLIENT	Additional command to install the appropriate database library
MariaDB	myslq	$ npm i mysql --save
MSSQL	msslq	$ npm i mssql --save
MySQL	myslq	$ npm i mysql --save
PostgreSQL	pg	$ npm i pg --save
SQLite3	sqlite	$ npm i sqlite3 --save

The CONNECTION_CONFIG represents the connection parameters to the database.

Constant	Default	Description
host	'localhost'	Database host name
user	'root'	Database user name
password	''	Database password
database	'database'	Database name
timezone	'+00:00'	Database timezone

Example:

// CONNECTION_CONFIG
{
  host: {YOUR_DATABASE_HOST},
  user: {YOUR_DATABASE_USER},
  password: {YOUR_DATABASE_PASSWORD},
  database: {YOUR_DATABASE_NAME},
  timezone: {YOUR_DATABASE_TIMEZONE}
}

• buildRoutes(API_CONFIG)

The API_CONFIG represents the API configuration.

Constant	Description
base	Main path of the API
pages	Pages of the API
table	Main configuration for all tables
routes	All API routes

Example:

// API_CONFIG
{
  base: '/api',
  pages: PAGE_CONFIG,
  table: TABLE_CONFIG,
  routes: ROUTE_CONFIG     
}

The PAGE_CONFIG represents the global configuration of the pages.

Constant	Default	Description
docs	true	Indicates if the docs page is visible
monitor	true	Indicates if the monitor page is visible

Example:

// PAGE_CONFIG
{      
  docs: true,  
  monitor: true
}

The TABLE_CONFIG represents the global configuration of table.

Constant	Default	Description
created_date	'created'	Name of the creation date column
modified_date	'modified'	Name of the modified date column
active	'deleted'	Name of the deleted column

Example:

// TABLE_CONFIG
{
  created_date: 'created',
  modified_date: 'modified',
  active: 'deleted'
}

The ROUTE_CONFIG represents the route groups.

Constant	Default	Description
tb	[]	Group for tables or views
fn	[]	Group for functions
sp	[]	Group for stored procedures

Example:

// ROUTE_CONFIG
{      
  tb: [
    TB_CONFIG,
    ...
  ],  
  fn: [
    FN_CONFIG,
    ...
  ],
  sp: [
    SP_CONFIG,
    ...
  ]
}

The TB_CONFIG represents the table or view configuration.

Constant	Default	Description
table	'table'	Table name
view	null	View name
event	'TABLE'	Event name (For socket.io event. => 'TABLE_INSERTED', 'TABLE_UPDATED', 'TABLE_DELETED')
methods	['GET', 'POST', 'PUT', 'DELETE']	List of methods to implement ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'SEARCH', 'SEARCH_COLUMN', 'POST_BATCH', 'PUT_BATCH', 'PATCH_BATCH', 'DELETE_BATCH']
columns	[]	List of columns (Used only by methods 'POST', 'PUT', 'PATCH', 'POST_BATCH', 'PUT_BATCH' and 'PATCH_BATCH')

Example:

// TB_CONFIG
{      
  table: 'table',  
  view: null,
  event: 'TABLE',  
  methods: ['GET', 'POST', 'PUT', 'DELETE'],  
  columns: [
    COLUMN_CONFIG,
    ...
  ]
}

The COLUMN_CONFIG represents the column of table.

Constant	Default	Description
name	''	Column name
primary	false	Defines if column is primary key
hidden	false	Defines if the column data will be sent in the response

Example:

// COLUMN_CONFIG
{
  name: 'id', 
  primary: true,
  hidden: true
}

The FN_CONFIG represents the function configuration.

Constant	Default	Description
function	'function'	Function name
params	[]	List of params

Example:

// FN_CONFIG
{      
  function: 'function',  
  params: [
    PARAM_CONFIG,
    ...
  ]
}

The SP_CONFIG represents the stored procedure configuration.

Constant	Default	Description
procedure	'procedure'	Stored procedure name
params	[]	List of params

Example:

// SP_CONFIG
{      
  procedure: 'procedure',  
  params: [
    PARAM_CONFIG,
    ...
  ]
}

The PARAM_CONFIG represents the param of function or stored procedure.

Constant	Default	Description
name	''	Param name

Example:

// PARAM_CONFIG
{
  name: 'n'
}

Examples

• MySQL or MariaDB.
• PostgreSQL.
• SQLite3.

Migrations

• For version 0.x to 1.x.

Author

@victor-valencia.

License

Licensed under the MIT license.