Route Generation

KambojaJS route generation system uses Kecubung to load the metadata information e.g. namespace, class, method, parameters, decorators etc.

Note Kecubung directly reads the .js files and returned reflection meta data. When using ES5 there is no standard code style to define classes and namespaces, that makes generating type meta data difficult. Just for simple example you can compare ES5 class generated using TypeScript and Babel.

Currently now Kecubung only support code style generated using TypeScript, so it is required to use TypeScript at the moment.

Note we can add support for Babel later, based on interests.

Route Generation System

To generate controller into routes, there are some transformation step with a priority. Each of them generates a metadata called RouteInfo contains route, method info, class info etc.

Below is list of transformers used by route generation system ordered by its priority:

  1. Decorator transformer, generates route based on decorator
  2. Api convention transformer, generates route based on action/parameter name follow the Restful api best practice
  3. Default transformer, generate route based on namespace controller action and parameter names.

Classes metadata loaded from the .js source code then passed to those transformers start from the top priority to the bottom. If the metadata match the condition it will be processed and returned else it will be pass through the next transformer.

We will start discussion of each transformer from the bottom, because default transformer use frequently then other transformer and have basic idea of the route generation system.

Default Transformer

Default transformer will generate each name of namespace, controller, action, parameters like below format:

GET <namespace>/<controller>/<action>?<parameters>
  • Http Method By default GET http method will be use, unless an @route decorator used to override the generator.
  • Namespace All namespaces name translated into url path lower cased. Nested namespace translated into separate path.
  • Controller All controllers translated into path, lower cased, controller suffix omitted.
  • Action All actions translated into path, lower cased.
  • Parameters All parameters not translated into route path, but kept on the metadata for further it will be used by the parameter binder to bind the query string data with the action parameter

example:

import { Controller } from "kamboja-express"

export namespace Public.Api.V1 {
    export class UsersController extends Controller {
        getDetail(id:string, category:string){}
    }
}

Above code will generated into:

GET /public/api/v1/users/getdetail

Api Convention Transformer

Api Convention transformer only applied to all controllers inherited from ApiController. Api Convention designed to create Restful API using some best practices.

Api convention transformer will locate for specialized action get, list, delete, add, replace and modify then transform it into appropriate http method and url:

Action Method Url
get(id, <optional>) GET /items/:id
list(<optional>) GET /items
add(body, <optional>) POST /items
replace(id, body, <optional>) PUT /items/:id
modify(id, body, <optional>) PATCH /items/:id
delete(id, <optional>) DELETE /items/:id

<optional> parameters mean you can add as many parameter as you like no limitation added to it.

Parameter name is free you can rename the id parameter as uniqueId, customerId or even email etc, but remember the parameter order is mandatory, see more info in parameter binding.

import { ApiController } from "kamboja-express"
 
export class ItemsController extends ApiController {
    get(id:string) {}
    add(item){}
    list(offset:number, limit = 50){}
    modify(id:string, item){}
    replace(id:string, item){}
    delete(id:string){}
}

Above code will generated into:

GET    /items/:id
POST   /items
GET    /items?offset=0&limit=<optional>
PATCH  /items/:id
PUT    /items/:id
DELETE /items/:id

Decorator Transformer

Decorator transformer @route uses typescript decorator feature to identify controller action and transform appropriate action into url.

Decorator transformer have the highest priority on generating route, it means all above controller / action will not take effect if it decorated.

Decorator Method
@route.get(<route>) GET
@route.post(<route>) POST
@route.put(<route>) PUT
@route.patch(<route>) PATCH
@route.delete(<route>) DELETE
@route.root(<route>) -

@route.root() is special decorator used to decorate controller. Refer to Http Decorator for more information.

import { ApiController, http } from "kamboja-express"
 
export class ItemsController extends ApiController {
    @route.patch("/items/:id")
    get(id:string, data) {}
}

Above code showing specialized action get that by default will be generated into GET /items/:id. Instead it will generated into PATCH /items/:id