JSON API Service

A library to simplify web API service creation. It relies on express and routing-controllers.

The library reduces a boilerplate to spin-up a rest API service. Also this library:

• Sets up HEAD request handler (HEAD requests appear as a part of CORS workflow).
• Handlers CORS but only in development (local) mode.
• Handles HTTP errors and responds with proper JSON and HTTP status code.

Usage

Install library and required peer dependencies:

npm i @gerkirill/json-api-service routing-controllers@^0.10.4 class-transformer@^0.5.1 class-validator@^0.14.1 reflect-metadata
npm i -D @types/node typescript

Note: versions of class-transformer and class-validator are defined as peer dependencies of the routing-controllers^0.10.4.

Usage example:

import { createApplication } from '@gerkirill/json-api-service';
import { Get, JsonController } from 'routing-controllers';

const BASE_PATH = '/api';
const PORT = 5000;

@JsonController()
class HealthController {
  // http://localhost:5000/api/health/
  @Get('/health') 
  public async getHealth() {
    return { status: 'ok' };
  }
}

const app = createApplication({
  routePrefix: BASE_PATH,
  controllers: [HealthController],
  errorHandler: (error) => console.error(error),
});
app.listen(PORT, () => {
  console.log(`Server listening at port ${PORT}`);
});

Also, make sure the following compilerOptions are set in your tsconfig.json:

{
  "experimentalDecorators": true,
  "emitDecoratorMetadata": true
}

createApplication accepts configuration object with the following fields:

• routePrefix (optional, string) A url fragment to be added to all controllers, e.g.: /api/v1.
• controllers (array) Array of controller classes annotated with @Controller() or @JsonController().
• middlewares (optional, array) Array of middleware classes to use globally.
• interceptors (optional, array) Array of interceptors to use globally, annotated with @Interceptor().
• earlyBootstrapFn (optional, function(app) => void) Function to execute on app before it is passed to useExpressServer().
• errorHandler (optional, function(err) => void) A callback invoked by the custom HTTP error handler this library provides. If error handler is not set - errors are logged to console with console.error().

Contributing

Upon update of routing-controllers - make sure to update peer dependency versions in package.json (dev dependencies section) and in README. Also, you may get a warning like this one class-transformer 0.3.2 (0.5.1 is available) deprecated - please don't upgrade unless your version of routing-controllers requires exactly this version.