Express Rest Api Boilerplate

A RESTful API based on generator-rest.

See the API's documentation.

Commands

After you generate your project, these commands are available in package.json.

npm test # test using Jest
npm run coverage # test and open the coverage report in the browser
npm run lint # lint using ESLint
npm run dev # run the API in development mode
npm run prod # run the API in production mode
npm run docs # generate API docs

Playing locally

First, you will need to install and run PostgreSQL (12 version is recommended)

You should have docker to run following command

$ sh run_postgres.sh
$ npm run dbmigrate

Then, run the server in development mode.

$ npm run dev
Express server listening on http://0.0.0.0:9000, in development mode

If you choose to generate the authentication API, you can start to play with it.

Note that creating and authenticating users needs a master key (which is defined in the .env file)

Create a user (sign up):

curl -X POST http://0.0.0.0:9000/users -i -d "email=test@example.com&password=123456&access_token=MASTER_KEY_HERE"

It will return something like:

HTTP/1.1 201 Created
...
{
  "id": "57d8160eabfa186c7887a8d3",
  "name": "test",
  "email": "test@example.com",
  "createdAt": "2016-09-13T15:06:54.633Z"
}

Authenticate the user (sign in):

curl -X POST http://0.0.0.0:9000/auth -i -u test@example.com:123456

It will return something like:

HTTP/1.1 201 Created
...
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "user": {
    "id": "57d8160eabfa186c7887a8d3",
    "name": "test",
    "email": "test@example.com",
    "createdAt":"2016-09-13T15:06:54.633Z"
  }
}

Now you can use the eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 token (it's usually greater than this) to call user protected APIs. For example, you can edit user using the PUT /users/me endpoint only accessible to authenticated users. Then, to edit a user you must pass the access_token parameter.

curl -X PUT http://0.0.0.0:9000/users/me -i -d "name=test2&access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

It will return something like:

HTTP/1.1 201 Created
...
{
  "id": "57d8160eabfa186c7887a8d3",
  "name": "test2",
  "email": "test@example.com",
  "createdAt":"2016-09-13T15:06:54.633Z"
  "updatedAt":"2016-09-13T15:22:39.846Z"
}

Some endpoints are only accessible by admin users. To create an admin user, just pass the role=admin along to other data when calling POST /users.

Deploy

Here is an example on how to deploy to Heroku using Heroku CLI:

# start a new local git repository
git init

# create a new heroku app
heroku apps:create my-new-app

# add heroku remote reference to the local repository
heroku git:remote --app my-new-app

# set the environment variables to the heroku app (see the .env file in root directory)
heroku config:set MASTER_KEY=masterKey JWT_SECRET=jwtSecret

# commit and push the files
git add -A
git commit -m "Initial commit"
git push heroku master

# open the deployed app in the browser
heroku open

The second time you deploy, you just need to:

git add -A
git commit -m "Update code"
git push heroku master

Directory structure

Overview

You can customize the src, models, routes and services directories.

src/
├─ models/
│  └─ social_network.js
│  └─ user.js
├─ routes/
│  ├─ users/
│  │  ├─ controller.js
│  │  ├─ index.js
│  │  ├─ validationSchema.js
│  └─ index.js
├─ services/
│  ├─ express/
│  ├─ apple/
│  ├─ github/
│  ├─ google/
│  ├─ jwt/
│  ├─ logger/
│  ├─ mail/
│  ├─ passport/
│  ├─ postgres/
│  ├─ response/
│  ├─ vk/
│  ├─ facebook/
│  ├─ passport/
│  ├─ sendgrid/
│  └─ your-service/
├─ app.js
├─ config.js
└─ index.js

src/routes/

Here is where the API endpoints are defined. Each API has its own folder.

src/models/model.js

It defines the Mongoose schema and model for the API endpoint. Any changes to the data model should be done here.

src/routes/some-endpoint/controllers/some-controller.js

This is the API controller file. It defines the main router middlewares which use the API model.

src/routes/some-endpoint/index.js

This is the entry file of the API. It defines the routes using, along other middlewares (like session, validation etc.), the middlewares defined in the contollers/some-controller.js file.

services/

Here you can put helpers, libraries and other types of modules which you want to use in your APIs.

Credits

Thanks to generator-rest