api-server-boilerplate

A stripped down API boilerplate built around NodeJS and OpenAPI (Swagger) V3.

Configuration

Set the following environment variables

Variable	Default	Notes
PORT	8282	The port the server listens on

API Routes

If it's running locally (see below) point a browser at any of the following routes:

• localhost:8282
• localhost:8282/ping
• localhost:8282/api/v1/hello/some name
• localhost:8282/api/v1/snooze

and see the API docs at

• localhost:8282/docs

What's the point of this?

I write a lot of APIs and have distilled my current best-practice into this codebase to save myself time, and as example code for other developers wondering how to do this sort of stuff.

What do you do with it?

This is a GitHub Template so either click the 'use this template' button above, or clone this rep, or fork it, nuke the existing .git data and replace with your own git init and git flow init edit the README.md file, add your own details to api.yml and add routes to src/api/ as you like.

What's included?

• a couple of root-level API routes and simple controllers

  • src/api/ping
  • src/api/versions

• a versioned API route and controller

  • src/api/v1/hello

• example of an asynchronous route using route-async

  • src/api/v1/snooze

• automatic construction of api controller routes using traverse-folders

• automatic linking of swagger paths to controllers using swagger-routes-express

• request and response validation using express-openapi-validator

• automatic generation of API docs using swagger-ui-express

• simple logging (swap out the code in src/utils/logger to add your own)

• standardised node-http-error and http-status-codes and simple generic and notFound error handlers

• dotenv support

• the swagger editor as an easy to invoke docker image

• simple project.toml buildpacks config.

Code quality

• unit testing using

  • mocha,
  • sinon,
  • chai, and
  • proxyquire

• request and response mocks using mock-req-res

• 100% unit test coverage using nyc

• integration testing using supertest

• code quality using eslint and prettier

• circleci integration

• snyk integration

What's not included?

I've paired this right back to the simplest, most generic API I could, so there's no

• authentication (add passport and update src/utils/makeApp and add appropriate security blocks to api.yml)
• rate limiting
• middleware (roll your own and update src/utils/makeApp)
• monitoring
• sockets or event listeners
• databases, search systems, etc

Development

Branches

Branch	Tests	Code Coverage	Audit	Comments
develop				Work in progress
main				Latest Production Release

Prerequisites

• NodeJS, I use nvm to manage Node versions — brew install nvm.
• Docker if you want to use the Swagger Editor, or you wish to use a buildpack. Use Docker for Mac, not the homebrew version.
• Pack to use buildpacks — brew install buildpacks/tap/pack

To build and run locally

Clone this (or better yet, fork it then clone your fork)

npm install
npm start

You can then go to localhost:8282/docs to see the docs.

.env file

You can put environment variables in a .env file.

Buildpacks.

You can use an heroku buildpack as follows:

pack build api-server-boilerplate --builder heroku/buildpacks:18
docker run api-server-boilerplate

Or tweak the project.toml file to use whatever buildpacks and environment variables you wish.

Development Helpers

Service	Port	Command	Notes
Swagger Editor	8080	npm run swagger	The swagger editor

Copy and paste the api.yml file into the editor to edit it.

Testing

• npm test to run the unit tests
• npm run test:server will run the integration tests
• npm run lint will lint it
• npm run prettier will prettify it
• npm run test:unit:cov will run the unit tests with code coverage

Contributing

Please see the contributing notes.