Skip to main content


Creates REST endpoints based on Herbs entities and use cases.

Getting started


$ npm install @herbsjs/herbs2rest


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',
entity: require('../entities/user')
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.

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. If an entity is informed, its ID field will be used as a reference for the endpoint. If neither an entity nor a string is informed, the default id field will be 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


HTTP Status Code and Err

Herbs2rest translates Herbs Known Errors​ to HTTP status code as described in the documentation.


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


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

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


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