Skip to main content

Herbs2Rest

Create a REST API based on herbs entities (gotu) and use cases (buchu).

Getting started

Installing

  npm install @herbsjs/herbs2rest

Using

Use the method generateRoutes to generate api rest routes based on usecases.

herbs2rest works with express in version 4.x.

Controller List

The method needs a list of controllers like the example below:

const controllerList = [
{
name: 'lists',
getAll: { usecase: require('../usecases/getLists'), controller: require('../controller') },
getById: { usecase: require('../usecases/getLists'), id: 'listId' },
post: { usecase: require('../usecases/createList') },
put: { usecase: require('../usecases/updateList') },
delete: { usecase: require('../usecases/deleteList') }
}
]

The name field is the name of the route (Ex. https://example.com/lists)

fieldcontroller
getAllGET /{name}/
getByIdGET /{name}/{id}
postPOST /{name}/
putPUT /{name}/{id}
deleteDELETE /{name}/{id}

The id field is a string representing the id field in the use case request and can be used for GetById, Put and Delete. The default value is "id".

The controller field a function that replaces the default controller.

Custom Controller

To create a custom controller, it is necessary to follow this pattern.

const controller = async (usecase, req, user, res, next) => {
// Implementation
}

Each method parameter has different data:

  • usecase: usecase in (buchu) pattern.
  • req: body, query and params of route.
  • user: parameter passed in the request.
  • res: response object of express.
  • next: allows the next queued route handler/middleware to handle the request.

Generate Routes

Generating and using new express routes:

const express = require('express')
const { generateRoutes } = require('@herbsjs/herbs2rest')

const app = express()
const routes = new express.Router()

generateRoutes(controllerList, routes, true) // true = console info endpoints

app.use(routes)

Authorization

All use cases must implement the authorize method and receive a user for authentication if using the default controller.

Example:

const { Ok, Err, usecase } = require('@herbsjs/herbs')

const testUseCase = (injection) =>
usecase('Test UseCase', {
authorize: async (user) => {
if (user === 'admin')
return Ok()
else
return Err('Invalid user')
}
})

Example

Additionally you can view a simple demo application of this library in todolist-on-herbs.

How to contribute

If you would like to help contribute to this repository, please see CONTRIBUTING


License