@gerkirill/json-api-service
v1.0.1
Published
A library to simplify web API service creation, based on routing-controllers.
Downloads
3
Readme
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.