amida-tech/api-boilerplate

README

Amida API Boilerplate

Overview

This is a boilerplate application for building REST APIs in Node.js using ES6 and Express. Intended for use with PostgreSQL using Sequelize ORM.

Features

Feature	Summary
ES6 via Babel	ES6 support using Babel.
Authentication via JsonWebToken	Supports authentication using jsonwebtoken.
Code Linting	Uses the airbnb-base style guide with ESLint parsing modern ES6 syntax
Auto server restart	Restart the server using nodemon in real-time anytime an edit is made, with babel compilation and eslint.
ES6 Code Coverage via Jest	Supports code coverage of ES6 code using Jest. Code coverage reports are saved in `coverage/` directory post `yarn test:coverage` execution. Open `coverage/lcov-report/index.html` to view coverage report. `yarn test:coverage` also displays code coverage summary on console.
Debugging via debug	Instead of inserting and deleting console.log you can replace it with the debug function and just leave it there. You can then selectively debug portions of your code by setting DEBUG env variable. If DEBUG env variable is not set, nothing is displayed to the console.
Promisified Code via bluebird	We love promise, don't we? All our code is promisified and even so our tests via supertest-as-promised.
API parameter validation via express-validation	Validate body, params, query, headers and cookies of a request (via middleware) and return a response with errors; if any of the configured validation rules fail. You won't anymore need to make your route handler dirty with such validations.
Pre-commit hooks	Runs lint and tests before any commit is made locally, making sure that only tested and quality code is committed
Secure app via helmet	Helmet helps secure Express apps by setting various HTTP headers.
Uses yarn over npm	Uses yarn package manager by facebook. You can read more about it here

CORS support via cors
Uses http-status to set http status code. It is recommended to use httpStatus.INTERNAL_SERVER_ERROR instead of directly using 500 when setting status code.
Has .editorconfig which helps developers define and maintain consistent coding styles between different editors and IDEs.

Getting Started

Install yarn:

npm install -g yarn

Install dependencies:

yarn

Set environment (vars):

cp .env.example .env

Start server:

# Ensure that a PostgreSQL database is running on your localhost

# Start server
yarn start

# Selectively set DEBUG env var to get logs
DEBUG=amida-api-boilerplate:* yarn start

Tests:

# Run tests written in ES6
yarn test

# Run test along with code coverage
yarn test:coverage

# Run tests on file change
yarn test:watch

Lint:

# Lint code with ESLint
yarn lint

# Run lint on any file change
yarn lint:watch

Other gulp tasks:

# Wipe out dist and coverage directory
gulp clean

# Default task: Wipes out dist and coverage directory. Compiles using babel.
gulp

Deployment

# compile to ES5
1. yarn build

# upload dist/ to your server
2. scp -rp dist/ user@dest:/path

# install production dependencies only
3. yarn --production

# Use any process manager to start your services
4. pm2 start dist/index.js

Logging

Universal logging library winston is used for logging. It has support for multiple transports. A transport is essentially a storage device for your logs. Each instance of a winston logger can have multiple transports configured at different levels. For example, one may want error logs to be stored in a persistent remote location (like a database), but all logs output to the console or a local file. We just log to the console for simplicity, you can configure more transports as per your requirement.

API logging

Logs detailed info about each api request to console during development.

Error logging

Logs stacktrace of error to console along with other details. You should ideally store all error messages persistently.

Code Coverage

Get code coverage summary on executing yarn test:coverage

yarn test:coverage also generates HTML code coverage report in coverage/ directory. Open lcov-report/index.html to view it.

Docker Deployment

Docker Compose:

# In `.env` file, assign `UNIQUE_NAME_PG_HOST` to amida-db
1. sed -i s/localhost/amida-db/ .env

# Run:
2. yarn build && docker-compose up

AWS Deployment

The basic steps for deploying to AWS are:

Run the Packer script, template.json
Run the Terraform script.

Further details can be found in the deploy directory.