Blog

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

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!

Add Your Comment

(2)

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 https://www.ortussolutions.com/blog/rest2016-coldbox-rest-basehandler-module ;-)

Recent Entries

Into the Box 2024 Last Early Bird Days!

Into the Box 2024 Last Early Bird Days!

Time is ticking, with less than 60 days remaining until the excitement of Into the Box 2024 unfolds! Don't let this golden opportunity slip away; our exclusive Early Bird Pricing is here for a limited time only, available until March 31st. Why wait? Secure your seat now and take advantage of this steal!

Maria Jose Herrera
Maria Jose Herrera
March 20, 2024
Ortus February Newsletter 2024

Ortus February Newsletter 2024

Welcome to Ortus Solutions’ monthly roundup, where we're thrilled to showcase cutting-edge advancements, product updates, and exciting events! Join us as we delve into the latest innovations shaping the future of technology.

Maria Jose Herrera
Maria Jose Herrera
March 06, 2024
Unveiling the Future of CFML Development - 3rd Round of Sessions

Unveiling the Future of CFML Development - 3rd Round of Sessions

Welcome back to our journey into the future of CFML development! As excitement continues to build for Into the Box 2024, we're thrilled to bring you the latest updates on what promises to be a transformative event. Continuing our blog post series, let's delve deeper into the third wave of session releases and discover the key surprises awaiting attendees. Learn More

Maria Jose Herrera
Maria Jose Herrera
March 01, 2024