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

Protect Your Data with Proactive Database Security Management

Protect Your Data with Proactive Database Security Management

In today’s digital age, data is among the most valuable assets for businesses. It powers decision-making, customer engagement, and operational efficiency. However, as data volumes grow, so do the risks associated with managing it. Ensuring database security and compliance is no longer optional—it’s a necessity.


The Evolving Landscape of Database Security

Modern databases face a myriad of challenges, from increasingly sophisticated cyber threats to strin...

Cristobal Escobar
Cristobal Escobar
December 06, 2024
The Experts Driving BoxLang: The Team Behind the Revolution

The Experts Driving BoxLang: The Team Behind the Revolution

Introduction

BoxLang is not just another programming language; it’s a revolutionary step forward for JVM environments. But who are the minds behind this innovation? Meet the talented team of architects, developers, and engineers who have combined decades of experience to create BoxLang—a language built for scalability, performance, and efficiency. Let’s explore their ex...

Cristobal Escobar
Cristobal Escobar
December 04, 2024
Why BoxLang is the Modern Software Development Evolution You’ve Been Waiting For?

Why BoxLang is the Modern Software Development Evolution You’ve Been Waiting For?

In today’s software landscape, developers need tools that deliver flexibility, efficiency, and modernization. With decades of open-source expertise, Ortus Solutions introduces BoxLang—our most ambitious project yet. Built for the JVM, BoxLang integrates seamlessly with Java, offering powerful features for scalable, high-performance web applications. Fully compatible with CFML, it ensures a smooth transition and expanded capabilities for existing projects.

Maria Jose Herrera
Maria Jose Herrera
December 04, 2024