Skip to main content


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

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',
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. 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


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.

How to contribute​

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