@bubojs/api

Api

Back to Main Menu

The API package is the heart of bubo, it creates the routes, registers the middleware and orchestrates everything, it provides decorators to easily create routes via classes and functions.

Creating a controller

To make a controller the file that contains the class must end with "Controller.ts", a search is made in the project file names to find the different controllers

Then the Controller class must be decorated with a

@Controller() 

This will result in the creation of a sub route, the name of this sub route will be the name of the controller class without the controller at the end, written in snake case and all pluralized the decorator takes an optional options object as parameter which contains two fields:

export interface ControllerParams {
  repository?: BuboRepository<unknown>
  overrideRouteName?: string
}

repository allows to define a repository which will allow to generate routes automatically overrideRouteName allows to define another route name than the one generated automatically

Adding an automatic route

To build an automatic route you need to provide the controller with a repository (currently only sequelize is available)

The repository

import { SequelizeBaseRepository } from '@bubojs/sequelize'
import { SqlzModel } from './SqlzModel'

class MyRepository extends SequelizeBaseRepository<SqlzModel> {
  constructor() {
    super(SqlzModel)
  }
}
export const myRepositoryInstance = new MyRepository()

The controller

import { Controller, DefaultActions, BeforeMiddleware, Post, Get, BodyFormat, Body } from '@bubojs/api'
import { myRepositoryInstance } from './MyRepository'

@Controller({ repository: myRepositoryInstance })
class DropController {}

For security reasons no automatic route is built by default, you have to activate the ones you need, for that you have to define one by one the routes by creating a field in the controller with this bias:

import { Controller, DefaultActions, BeforeMiddleware, Post, Get, BodyFormat, Body } from '@bubojs/api'
import { myRepositoryInstance } from './MyRepository'

@Controller({ repository: myRepositoryInstance })
class BaseController 
{
    
    [DefaultActions.CREATE_ONE](){}
    [DefaultActions.UPDATE_ONE](){}
    [DefaultActions.GET_ONE]() {}
    [DefaultActions.GET_MANY]() {}
    [DefaultActions.DELETE_ONE]() {}
}

These routes create a direct request to the database, you can add options to this request via our dedicated middleware (see below), or add your own options by passing them in req.$sequelize ( ⚠️ beware of the interaction between several options middlewares) So we have the following routes:

• POST /base/
• PUT /base/:id
• GET /base/:id
• GET /base/
• DELETE /base/:id

Adding a custom route

A custom route is added via a decorator:

import { Controller, DefaultActions, BeforeMiddleware, Post, Get, BodyFormat, Body } from '@bubojs/api'

@Controller()
class TestController 
{
  @Get('/hello_world')
  greetings(){
    return 'hello world'
  }
}

we have just created a route that returns hello_world on address:port/test/hello_world

Passing parameters on custom routes

To pass parameters to your functions on custom routes we have developed decorators to extract data from req.query, req.params, req.body using respectively @Query('fieldName'), @Params('paramName'), @Body('fieldName') example:

import { Controller, Post, Get, Body, Query } from '@bubojs/api'
@Controller()
class MyController
{
  @Get('/hello_world')
  greetings(@Query('username') username: string){
    return `hello ${username}`
  }
}

will return hello bubo on the Get {{api}}/drop/hello_world?username=bubo

Modify the parser

By default the route parser is set to AUTO it will accept all formats it is able to parse (RAW, TEXT, JSON, URL_ENCODED) but you can also force a format, the options are:

• RAW
• TEXT
• JSON
• AUTO (parse with the best identified method)
• SKIP (does not parse the body in case you want to put your own parser in the middleware)
• URL_ENCODED

example:

import { Controller, Post, Body, BodyFormat } from '@bubojs/api'
@Controller()
class MyController
{
  @Post('/test', { bodyFormat: BodyFormat.JSON })
  test(@Body('username') username: string){
    return `hello ${username}`
  }
}

In this case the route will refuse anything that is not in JSON format

Raw Handler

When you build a custom route the buboJs api will wrap your function to retrieve its result and store it in req.result, this will allow you to call other middleware afterwards to perform formatting operations for example. You can however define yourself the handler and manage directly the call of the following middleware (or not), for that you will provide to the decorator of the custom route not the function you want to execute but a constructor of the handler you want to call, it is also necessary to activate the option {rawHandler : true} in the decorator of the route example:

import { Controller, Post, Body, BodyFormat } from '@bubojs/api'
@Controller()
class MyController
{
  @Get('/hello_world', { rawHandler: true, bodyFormat: BodyFormat.AUTO })
  builder() {
    return (req: any, res: any, next: Function) => {
      res.status(200).json(`hello ${req.query.username}`)
    }
  }
}

Back to Main Menu

Editor