REST2016 - ColdBox REST Template

Luis Majano March 03, 2016

Spread the word

Luis Majano

March 03, 2016

Spread the word

Share your thoughts

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


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


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!

Add Your Comment


Apr 28, 2016 10:51:09 UTC

by Daniel Schmid

I would be nice to have this skeleton as a "module template". That would allow to build versions of the API (v1,v2,v3) or just different sub-APIs for different purposes (internal, public, custom)... all in modules.

Apr 28, 2016 10:57:27 UTC

by Daniel Schmid

Found it ;-)

Recent Entries

Into the Box - Updates as of May 16th, 2022

Into the Box - Updates as of May 16th, 2022

Into the Box is sneaking up closer and closer. With so many announcements, we can't post them all to the Ortus Solutions blog, so we're going to just give you updates when we can. To read all of our blog posts from ITB, visit the site or subscribe to RSS

This week we're going to be announcing the first set of Sessions, some of the Speakers, and some more sponsors. Last week was a big week for Into the Box too, check out the highlights

Gavin Pickin
Gavin Pickin
May 16, 2022
Ortus Content Digest for week of May 13th

Ortus Content Digest for week of May 13th

We were busy this week, we released a lot of content for you... on the podcast, cfcasts, youtube, and our blog. Here's the summary in bite size pieces

Gavin Pickin
Gavin Pickin
May 13, 2022