RESTHapi Gen

RESTHapi Gen is a @hapijs/hapi plugin which generates a CRUD RESTful API from a given joi model.

Compatibility

RESTHapi Gen version	Hapi JS version	Joi Version
2.x.x and 3.x.x	20.x.x and 21.x.x	joi^17.x.x
1.x.x	19.x.x	@hapi/joi^17.x.x
0.x.x	18.x.x	@hapi/joi^15.x.x

TL;DR;

$ npm i @hapi/hapi joi mongoose rest-hapi-gen

const Hapi = require('@hapi/hapi');
const Joi = require('joi');
const Mongoose = require('mongoose');

const RestHapiGen = require('rest-hapi-gen');

(async () => {
  await Mongoose.connect('mongodb://localhost:27017/testdb', { useNewUrlParser: true, useUnifiedTopology: true });

  const server = Hapi.server({ port: 4000 });

  const petsCollectionConf = {
    collection: { name: 'pets' },
    schema: Joi.object({
      name: Joi.string().required(),
      tags: Joi.array().items(Joi.string()).default([]),
    }),
  };

  await server.register([{ plugin: RestHapiGen, options: petsCollectionConf }]);
  await server.start();

  console.log('Server running on %s', server.info.uri);
})();

Plugin configuration

Option	Type	Description
auth.enabled	boolean	Optional Whether to activate auth or not. Default: false
auth.client.id	string	Required OAuth 2.0 client id. It is required if $.auth.enabled === true
auth.client.secret	string	Required OAuth 2.0 client secret. It is required if $.auth.enabled === true
auth.client.kind	string	Optional OAuth 2.0 server kind. Default: keycloak
auth.scope.read	string[]	Optional OAuth 2.0 required scope list to access read actions. Default false
auth.scope.write	string[]	Optional OAuth 2.0 required scope list to access write actions. Default false
auth.server.url	string	Required OAuth 2.0 server. It is required if $.auth.enabled === true
auth.server.realm	string	Optional OAuth 2.0 server realm. Default: master
auth.session.cookie.name	string	Optional Name for the session cookie. Default: rest-hapi-gen-session
auth.session.enabled	boolean	Optional Whether to enable session or just bearer only auth mechanism. Default: true
auth.session.password	string	Optional The session encryption password. Default: Random generated
basePath	string	Optional Base path where the CRUD endpoints are attached. Default: '/'
collection.name	string	Required Name for the collection that is going to be created.
collection.pages.limit	number	Optional Default max limit for collection queries, it will be overrided if the API user uses collection?limit=x. Default: 10
health.enabled	boolean	Optional Whether to enable a health endpoint. Default: true
health.path	string	Optional Target path where the health endpoint will be set, it must start with /. Default: /_healthz
overrides.actions.GET_COLLECTION	Function	Optional Async function that will override the default handler for GET_COLLECTION action
overrides.actions.GET_RESOURCE	Function	Optional Async function that will override the default handler for GET_RESOURCE action
overrides.actions.CREATE_RESOURCE	Function	Optional Async function that will override the default handler for CREATE_RESOURCE action
overrides.actions.UPDATE_RESOURCE	Function	Optional Async function that will override the default handler for UPDATE_RESOURCE action
overrides.actions.DELETE_RESOURCE	Function	Optional Async function that will override the default handler for DELETE_RESOURCE action
rootPathRedirect	boolean	Optional Whether redirect from root path (/) to basePath path. Default: false
schema	Joi	Required Joi schema for the collection that is created.
tls	boolean	Optional Whether the server is using TLS externally/internally or not. Default: false

Override an action

If an action needs to be overrided, you must provide an async function that will be executed instead of the default one. This function will receive three args: request that will be a @hapijs/hapi request object, h that will be a @hapijs/hapi request toolkit and a model that will be a mongoose model which is based on the given schema.

NOTE: Your custom function must return an object that must to be valid against the Joi schema otherwise the server will return an internal server error.

...
const { ActionType } = RestHapiGen;
...
  const petsCollectionConf = {
    collection: { name: 'pets' },
    schema: Joi.object({
      name: Joi.string().required(),
      tags: Joi.array().items(Joi.string()).default([])
    }),
    // Override actions
    overrides: {
      actions: {
        // Override GET collection action
        [ActionType.GET_COLLECTION]: async (request, h, model) => {
          return await model.find();
        },
      },
    },
  };
...

In addition, you could configure Hapi server adding debug.request so you can see schema validation errors, to do so you must apply the following configuration to your Hapi server

...
const server = Hapi.server({
  port: 4000,
  debug: {
    request: ['*'],
  },
});
...

Configure authentication

Currently, RESTHapi Gen only support keycloak as authentication provider, a generated resource can be protected using OAuth 2.0 and keycloak server, see the following example.

const petsCollectionConf = {
  collection: { name: 'pets' },
  schema: Joi.object({
    name: Joi.string().required(),
    tags: Joi.array().items(Joi.string()).default([]),
  }),
  auth: {
    enabled: true,
    server: { url: 'https://auth.example.io', realm: 'pets' },
    client: { id: 'example-client', secret: 'example-client-secret' },
    scope: { read: ['pets:ro'], write: ['pets:rw'] },
  },
};

Deploy MongoDB

Docker

$ docker run -d --rm --name mymongo -p 27017:27017 mongo

Docker Compose

version: '3.7'

services:
  mongo:
    image: mongo
    ports:
      - 27017:27017

$ curl -sSL https://raw.githubusercontent.com/dani8art/rest-hapi-gen/master/docker-compose.yaml > docker-compose.yaml
$ docker-compose up -d

License

RESTHapi Gen is MIT licensed.