If you work alone, using a BaseHandler that might not seem like a big win, but when working with a team, uniformity is your friend. Even when working alone, one of the hardest things in programming is naming conventions, it’s been great using a set of conventions, especially since the base handler takes care of all the boiler plate you would normally write yourself.

Luis Majano went into more detail in yesterday’s article about what the BaseHandler gives you, which you can read here on REST2016 ColdBox REST Template. Lets look about how you can get it installed into your existing app.

Installation

Git Repo: https://github.com/Ortus-Solutions/cbox-cbrestbasehandler
You can simply drop it into the modules folder, or the easiest way, using CommandBox, you can install the module with one simple command.

box install cbrestbasehandler

With the module installed, all you have to do to add the base handler functionality to your handler is extend it... using the mapping automatically create for your by the module itself.

component extends="cbrestbasehandler.handlers.BaseHandler” {
    ...
}

Once that is done, the BaseHandler will intercept requests via the aroundHandler() method, giving you a uniform response to your rest calls.

So how do you use it?

As Luis mentioned in the last blog post, the BaseHandler creates a Response object, and puts it in the prc scope for you. Since Accessors are set to true, you can get and set values as needed. To simple setData, you can have a simple function like the index below.

any function index( event, rc, prc ){
    prc.response.setData( "Welcome to my ColdBox RESTFul Service" );
}

Of course, not every call is successful, how do I return an error, or set a statusCode? With the responseObject, you can just set the given attributes, shown below, and the BaseHandler will take care of the implementation, so you do not have to add all of that boiler plate yourself.

any function index( event, rc, prc ){
    prc.response
    .setError( true )
    .setErrorCode( 500 )
    .addMessage( "General application error: I broke it" )
    .setStatusCode( 500 )
    .setStatusText( "General application error" );
}

Base Handler wrapping everything?

Its great to have a uniform response, but what if you want to have some methods not use the BaseHandler aroundHandler() interceptor? Inside the handler, you can add a line of code, to exclude given events. If you would like to exclude receipt() and printHeader() functions, then you would add a line like the following.

this.aroundHandler_except     = “receipt,printHeader”;

Remember this month is a ROADSHOW all about REST. We have weekly webinars, don't miss out on all the great content.
Lets build some REST together.