One of the newest additions to the ColdBox application templates and also the CommandBox generation templates is our REST application template.  This template will get you started with creating ColdBox RESTFul services. The best way to start with it is by downloading CommandBox, as we will use this for generation, scaffolding and as your integrated server. Then we can start working on our RESTFul service. Once installed just type box to go into our interactive shell (Just make sure you are in the directory of your choosing)

mkdir myservice --cd
coldbox create app skeleton=rest name=MyService --installColdBox
    

Once you execute these CLI commands, you will have a new RESTFul service application ready to go.  The next step is to startup an ad-hoc server and test it out:
 

server start --rewritesEnable

This will open a browser window with the results of your first RESTFul service:
 

{"data":"Welcome to my ColdBox RESTFul Service","error":false,"messages":[],"errorcode":0}

Now let's check out the code.  The template will create the following folders for you:

• coldbox - The coldbox framework
• config - Your application configuration
• handlers - The handlers for your service
• models - Where you create model objects
• modules - Where you create modules
• tests - BDD/Unit tests

Routing

The two locations of interest for your RESTFul service are the config and handlers directory.  In your config directory you will find a routes.cfm template that contains all your RESTFul routing URL Mappings.  By default, ColdBox can manage any RESTFul call by convention by leveraging the /:module/:handler/:action? route. ColdBox also converts by convention ANY name-value pair that comes in any URL after the handler/action combinations and places them in the request collection structure (rc) that every event handler (controller) receives, e.g /handler/action/page/2/print/pdf

Handlers

Let's now delve into our handlers. The rest template creates a BaseHandler and Echo handler controllers for you. The BaseHandler is where a lot of magic is done in this template in order to alleviate some verbosity and provide uniformity to handlers that will be REST based. You can by all means remove it and just do things manually. With the base handler approach our handlers that perform RESTFul duties become extremely focused and simple:

/**
* My RESTFul Event Handler
*/
component extends="BaseHandler"{

	// REST Allowed HTTP Methods Ex: this.allowedMethods = {delete='POST,DELETE',index='GET'}
	this.allowedMethods = {};
	
	/**
	* Index
	*/
	any function index( event, rc, prc ){
		prc.response.setData( "Welcome to my ColdBox RESTFul Service" );
	}
	
}

The BaseHandler will create a Response object for you and place it in the prc scope for you. This response object is a simple CFC and you can find it in your models folder. You can then interact with this object in order to advice the base handler on what data to return back, which format, messages, errors, status codes and much more. The BaseHandler intercepts requests via the aroundHandler() method in order to bring uniformity to all RESTFul calls. So you don't have to worry about error trapping, security, etc. It can provide all that for you. It even detects your environment and if you are in development it will always add profiling and more debugging information as headers in the HTTP response.

This rest template can really accelerate the development of RESTFul services as many concerns are already taken care of for your: environment checking, security, uniformity, error trapping, format marshalling, URL routing convention, HTTP method security, and much more. Enjoy!