Nitrate Processed Mincemeat

    @appgeist/restful-api

    1.5.6 • Public • Published

    @appgeist/restful-api

    NPM version License

    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.

    Install

    npm i @appgeist/restful-api

    DownloadsWeekly Downloads

    26

    Version

    1.5.6

    License

    ISC

    Unpacked Size

    16.3 kB

    Total Files

    10

    Last publish

    Collaborators

    • icflorescu