@appgeist/restful-api
v1.5.6
Published
An opinionated, convention-over-configuration Express-based API restful server featuring yup validation
Downloads
75
Maintainers
Readme
@appgeist/restful-api
An opinionated, convention-over-configuration Express-based restful API server featuring yup validation.
Usage
Initialization
You can use @appgeist/restful-api
either as an Express middleware:
const express = require("express");
const api = require("@appgeist/restful-api");
const [host, port] = ["0.0.0.0", 3000];
express()
// other middleware
.use(api())
// other middleware
.listen(port, host, err => {
if (err) throw err;
// eslint-disable-next-line no-console
console.log(`Server listening on http://${host}:${port}...`);
});
...or directly:
const api = require("@appgeist/restful-api");
const [host, port] = ["0.0.0.0", 3000];
api().listen(port, host, err => {
if (err) throw err;
// eslint-disable-next-line no-console
console.log(`Server listening on http://${host}:${port}...`);
});
When initializing @appgeist/restful-api
you can optionally specify the folder containing the route handler definitions (defaults to ./routes
):
const path = require("path");
const api = require("@appgeist/restful-api");
const [host, port] = ["0.0.0.0", 3000];
api(path.join(__dirname, "api-routes")).listen(port, host, err => {
if (err) throw err;
// eslint-disable-next-line no-console
console.log(`Server listening on http://${host}:${port}...`);
});
Defining route handlers
Name your route handler definition modules get.js
, post.js
, put.js
, patch.js
or delete.js
and organize them in a meaningful folder structure that will get translated to rest API routes.
For instance:
routes/departments/get.js => GET /departments
routes/departments/post.js => POST /departments
routes/departments/[id]/patch.js => PATCH /departments/3
routes/departments/[id]/delete.js => DELETE /departments/3
routes/departments/[id]/employees/get.js => GET /departments/3/employees
routes/departments/[id]/employees/post.js => POST /departments/3/employees
routes/departments/[id]/employees/[id]/get.js => GET /departments/3/employees/165
routes/departments/[id]/employees/[id]/patch.js => PATCH /departments/3/employees/165
routes/departments/[id]/employees/[id]/delete.js => DELETE /departments/3/employees/165
Each module exports:
beforeRequest
- an optional before request handler function;onRequest
- a mandatory request handler function;paramsSchema
,querySchema
,bodySchema
- optional schemas to validate the incoming request params, query and body. These can be simple objects (for brevity, in which case they will be converted to yup schemas automatically) or yup schemas (for more complex scenarios, i.e. when you need to specify a.noUnknown()
modifier).
A function handler accepts an optional object parameter in the form of { params, query, body, req }
and must return the data that will be sent back to the client, or a Promise resolving with the data.
For simple cases when you don't care about validation, you can export just the handler, like so: module.exports = () => {/* handle request here... */};
.
Nested paths
For nested paths, ancestor-level parameter names are magically renamed with the help of pluralize.singular
:
routes/departments/[id]/employees/[id]/get.js -> params: { departmentId, id }
routes/departments/[id]/employees/[id]/projects/[id]/get.js -> params: { departmentId, projectId, id }
Default error handling
Validation errors
When request data validation fails, the client will receive a response with HTTP status code 400
/BAD_REQUEST
and a JSON body describing the error provided by yup.validate(data, { abortEarly: false })
:
{
"message": "There were 2 validation errors",
"errors": ["body.name is required", "body.description is required"]
}
Throwing errors
If a function handler throws an ApiError(httpStatusCode)
(also exported from this package), the client will receive a response with the specified HTTP status code and a JSON body like { "message": "Why it failed" }
.
The ApiError
constructor accepts an HTTP status code number or an object structured like { status, message }
.
Using the constructor without parameters will result in a respose with HTTP status code 500
and the following JSON body:
{
"message": "Internal Server Error"
}
Custom error handling
You can override the default error handling mechanism by providing a custom error handling function like so:
const path = require("path");
const api = require("@appgeist/restful-api");
const [host, port] = ["0.0.0.0", 3000];
api(path.join(__dirname, "api-routes"), {
errorHandler: ({ err, res }) => {
res.status(500).send("Error");
console.log(err.stack);
}
}).listen(port, host, err => {
if (err) throw err;
// eslint-disable-next-line no-console
console.log(`Server listening on http://${host}:${port}...`);
});
Example
routes/departments/get.js
:
const Department = require("models/Department");
// simple handler, without validation
module.exports = () => Department.listAll();
// ...or exports.onRequest = () => Department.listAll();
routes/departments/[id]/patch.js
:
const { object, number } = require('yup');
const { FORBIDDEN } = require('http-status-codes');
const { ApiError } = require('@appgeist/rest-api');
const Department = require('models/Department');
const ACL = require('utils/acl');
const Logger = require('utils/logger');
// schema can be a simple object
exports.paramsSchema = {
id: number().positive().integer().required()
};
// schema can be a yup object
exports.bodySchema = object({
name: string().min(2).max(20).required()
description: string().min(2).max(1000).required()
}).noUnknown();
exports.onRequest = async ({ params: { id }, body, req }) => {
// throwing an ApiError(403) will result in a 403 status code being sent to the client
if (!(ACL.isManager(req.userId))) throw new ApiError(FORBIDDEN);
const department = await Department.updateById(id, { data: body });
await Logger.log(`Department ${id} updated by user ${req.userId}`);
return department;
}
routes/departments/[id]/employees/[id]/get.js
:
const { number } = require('yup');
const Department = require('models/Department');
const Employee = require('models/Employee');
exports.paramsSchema = {
departmentId: number().positive().integer().required()
id: number().positive().integer().required()
};
exports.beforeRequest = ({ url }) => {
console.log(`Preparing to respond to ${url}`);
};
exports.onRequest = async ({ params: { departmentId, id } }) => {
const employee = await Employee.getById(id);
employee.department = await Department.getById(departmentId);
return employee;
}
License
The ISC License.