README.md

REST API Boilerplate for Node.js in TypeScript

A simple REST API boilerplate created using Hapi, Boom, Joiful, Prisma, Pagination, Swagger and OAuth2.

Warning: for production ready environments change this part as you prefer. This is a simple example, setup of a strong OAuth2 authorization server and advanced configurations are out of the scope of this guide

Table of contents

• REST API Boilerplate for Node.js in TypeScript
  • Setup
    • Environment configuration
    • OAuth2 server setup
    • Database initialization
  • Prisma client
  • Available endpoints:
  • Boilerplate workflow
  • Token refresh lifecycle
  • Others
    • Pull requests and Issues
    • TODO

Setup

Environment configuration

Prepare your development environment:

$ cp .env.dev .env

Or prepare your production environment:

$ cp .env.prod .env

OAuth2 server setup

Generate OAuth2 server secret:

$ export LC_CTYPE=C; cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1

Save secret it in .env*.

Store OAUTH_SECRET otherwise you will lose access to authorization server

Start all docker-compose services with:

$ docker-compose up -d

Remember to stop all services when finished with:

$ docker-compose down

Create your first OAuth client:

$ docker exec hydra \
  hydra clients create \
    --endpoint http://127.0.0.1:4445/ \
    --id <client-id> \
    --secret <client-secret> \
    --grant-types authorization_code,refresh_token \
    --response-types token,code \
    --callbacks http://localhost:3000/api/oauth/authorize

Replace <client-id> and <client-secret> with your custom values

Deploy a sample Login & Consent OAuth App:

$ docker run -d \
  --name hydra-consent \
  -p 9020:3000 \
  --network hydranet \
  -e HYDRA_ADMIN_URL=http://hydra-server:4445 \
  -e NODE_TLS_REJECT_UNAUTHORIZED=0 \
  oryd/hydra-login-consent-node:v1.3.2

Database initialization

Initialize database using Prisma migrations:

$ npx prisma migrate dev --name init

Create first user in database:

$ npm run seed

Prisma client

Execute a Prisma migration in development environment:

$ npx prisma migrate dev --name init

Execute a Prisma migration in production environment:

$ npx prisma migrate deploy

Generate Prisma client (after some changes to Prisma model file):

$ npx prisma generate

To introspect database use Prisma Studio:

$ npx prisma studio

Available endpoints:

REST API endpoint:

http://localhost:3000/api

Swagger endpoint:

http://localhost:3000/api-docs

Boilerplate workflow

Follow these steps to complete the setup

1. Use commands before to prepare the environment

2. Go to swagger endpoint:

http://localhost:3000/api-docs#/

3. Use default credentials:

Username: admin
Password: admin

4. Make a GET request to /api/oauth/authenticate

5. Copy the authUrl in the response body and open it in a new browser window

6. Login to sample app with credentials [email protected] as email, foobar as password and give consent

7. After authentication completed, copy the JWT token provided and use it to authorize REST API requests as JWT Bearer token

Token refresh lifecycle

In order to prevent access token expiration issues an access token lifecycle has been implemented to refresh it when it expires. If this situation occurs the current request is authorized anyways but starting from next one you should provide newly generated access token, coming back in the Authorization header of the current response.

This allows full transparency of access token expiration and refresh using the API

Others

Pull requests and Issues

Feel free to submit issues and pull requests if you want 😄

TODO

• Write tests
• Checks other TODOs in code