last edited bylmajano on 16-Nov-2011

History 

<< Back to Dashboard | << Projects Viewer

ColdBox Relax: ReSTful Tools For Lazy Experts

What is Relax? ColdBox Relax is a set of ReSTful tools for lazy experts. We pride ourselves in helping you (the developer) work smarter and ColdBox Relax is a tool to help you document your projects faster. ColdBox Relax provides you with the necessary tools to automagically model, document and test your ReSTful services. One can think of ColdBox Relax as a way to describe ReSTful web services, test ReSTful web services, monitor ReSTful web services and document ReSTful web services–all while you relax!

Requirements

• ColdBox Relax is a ColdBox 3 Module and can be installed in any ColdBox 3 application.
• ColdFusion 8 and above.
• MySQL, MSSQL, Oracle or PostgresSQL for Log Viewing Capabilities (Optional).

Installation

Download the ColdBox Relax module and drop into your ColdBox modules folder. Start your application and visit the relax entry point:

http://myapp.com/index.cfm/relax/home

• Download - http://coldbox.org/forgebox/view/coldbox-relax
• Source - https://github.com/coldbox/coldbox-relax

Capabilities

So what can you do with Relax?

• Define your ReSTful services via our awesome Relax DSL (Programmatic or Implicit)
• Generate ColdBox Routes from described ReSTful routes
• Using this DSL we will document your entire ReSTful web service and you will be able to export the documentation in the following formats:
  • HTML
  • PDF
  • Trac Wiki Markup
  • Mediawiki Wiki Markup (CodexWiki)
• Using the DSL you will also have access to our RelaxURL (pronounced "Relaxer") tool, from which you can test your ReSTful web services
• Use the RelaxURL tool to test against ANY ReSTful service
• Keep a history of your latest Relaxed test requests so you can rebuild your request and test again
• LogBox integration so you can use the RelaxLogs viewer to monitor and see your log db entries
• Programmatic DSL for configuration of your RESTful services

Videos

Relax Intro

Version 1.5 Features

Version 1.4 Features

How to start?

To start using Relax you should start by configuring the Relax module for operation, then create our Relax DSL for our ReSTful web services. Finally, we can move into the RelaxLogs setup so we can monitor the logs produced by our RESTful service.

Relax Module Configuration

Let's open the module's configuration file ModuleConfig.cfc and see what we can modify in it. Look for the settings structure, this is the configuration structure for the Relax module and you have some control over it. Below is the default configuration structure:

// Relax Configuration Settings
settings = {
	// Relax Version: DO NOT ALTER
	version = this.version,
	// The location of the relaxed APIs, in instantiation path
	apiLocationPath = "#moduleMapping#.resources",
	// Default API to load
	defaultAPI = "myapi",
	// History stack size, the number of history items to track in the RelaxURL
	maxHistory = 10,
	// logbox integration information needed for log viewer to work
	// this means that it can read tables that are written using the logbox's DB Appender.
	relaxLogs = {
		// THE CF DATASOURCE NAME
		datasource = "relax",
		// THE DB TO USE FOR LOGS, AVAILABLE ADAPTERS ARE: mysql, mssql, postgres, oracle
		adapter = "mysql",
		// THE TABLE WHERE THE LOGS ARE
		table 	= "api_logs",
		// PAGING MAX ROWS
		maxRows = 50,
		// PAGING CARROUSEL BANDGAP
		bandGap = 3
	}
};

Relax Module Settings

And here are the settings that you can modify:

RelaxLogs Settings

RelaxLogs structure settings:

Relax DSL

Once you have configured the Relax module setup and ready for operation you can start by defining your RESTful service. You will do this by creating a Simple CFC–usually in the root of the resource folder, for simplicity–named Relax.cfc or Relax.json. In this component or JSON file, you will create several public variables (using the this scope) that will define your service's parameters, headers, resources and so much more. You can also use our programmatic DSL, which is much cleaner than implicit data structures. This CFC will represent your RESTful service and ColdBox Relax will generate documentation from it, create testable URLs for you and it is a great way for you to model your service. Please note that if you use JSON for defining your service, it must validate according to the same structure elements you will see here. http://www.jsonlint.com is a great way for you to format and validate your JSON representations.

component{

	// relax dsl
	this.relax = {};
	
	// Global Headers
	this.globalHeaders = [];
	
	// Global Parameteres
	this.globalParameters = [];
	
	// Resources
	this.resources = [];
}

relax configuration

The following properties are used to understand your ReSTful service:

Here is a sample of a single entry point:

// This is where we define our ReSTful service, this is usually
// our first place before even building it, we spec it out.
this.relax = {
	// Service Title
	title = "My ReSTful Service",
	// Service Description
	description = "A very cool ReSTful Service",
	// Service entry point
	entryPoint = "http://www.myapi.com",
	// Does it have extension detection via ColdBox
	extensionDetection = true,
	// Valid format extensions
	validExtensions = "xml,json,jsont,wddx",
	// Does it throw exceptions when invalid extensions are detected
	throwOnInvalidExtension = false		
};

Here is a sample of a multiple entry point service:

// This is where we define our ReSTful service, this is usually
// our first place before even building it, we spec it out.
this.relax = {
	// Service Title
	title = "My ReSTful Service",
	// Service Description
	description = "A very cool ReSTful Service",
	// Service entry point
	entryPoint = {
		dev =  "http://dev.myapi.com",
		staging =  "http://stg.myapi.com",
		production =  "http://www.myapi.com"
	},
	// Does it have extension detection via ColdBox
	extensionDetection = true,
	// Valid format extensions
	validExtensions = "xml,json,jsont,wddx",
	// Does it throw exceptions when invalid extensions are detected
	throwOnInvalidExtension = false		
};

globalHeaders configuration

This section is optional and only used if you would like to describe the HTTP headers that your service will listen to in a global manner. For example, if you require a X-Auth-Token to ensure every request has been authenticated you would want to take advantage of this feature. As with the variables defined before these are an array of structures with the following keys:

Here is a sample:

// Global API Headers
this.globalHeaders = [
	// Sample global header, Available keys: name,description,required,default,type
	{name="apikey",description="The apikey needed for request authentication.",required=true}
];

globalParameters configuration

This section is optional and only used if you would like to describe the HTTP parameters that your service will listen to in a global manner. For example, if you require a security token to ensure every request has been authenticated, or a format variable you would want to take advantage of this feature. As with the variables defined before these are an array of structures with the following keys:

Here is a sample:

// Global API Parameters
this.globalParameters = [
	// Sample global parameter, Available keys: name,description,required,default,type
	{name="apikey",description="The apikey needed for request authentication.",required=true},
	{name="format",description="An optional format variable used for content negotiation",required=false, default="json"}
];

resources configuration

The following section is essential as it describes the ReSTful resources you will expose through your service. Please remember that order is important as it will be used to generate the ColdBox routes file, which in turn are your ReSTful routes. We will create a array of structures with the following keys for each resource:

Here is a sample:

// Define our Relaxed ReSTful resources in order just like you are defining routes
// Each header, parameter or placeholder is a structure with the following keys:
// {name="",type="",required="",default="",description=""}
this.resources = [
	{pattern="/api/users",handler="rest.user",action="list", defaultMethod="GET", defaultFormat="json"
	 description="Returns all users",
	 methods="GET",headers=[],parameters=[],placeholders=[]},
	 
	 {pattern="/api/user/:username",handler="rest.user",action="{'get':'view','post':'create','put':'update','delete','remove'}",
	  description="The representation for system users.  You can also interact with creation, updating and deletion via this resource",
	  methods="GET,POST,PUT,DELETE",
	  headers=[],
	  parameters=[
		{name="firstName",description="The user firstname. Only used on PUT and POST operations",required="false"},
		{name="lastName",description="The user lastname. Only used on PUT and POST operations",required="false"},
		{name="email",description="The user email. Only used on PUT and POST operations",required="false"}
	  ],
	  placeholders=[{name="username",description="The resource username to interact with",required=true}]}
];

That's it! Once your DSL is defined, you can start up your relax module and get cooking with it. Here are some screenshots and videos about Relax.

Schemas & Samples

You can define samples and schemas for your resources by using the response structure by using the schemas and samples keys, which in turn are array of definitions.

response={
	schemas=[
		{format="json", description="The following will be returned when the format requested is JSON.", body=fileRead("#dirPath#schemas/user/user.json") },
		{format="xml", description="The following will be returned when the format requested is XML.", body=fileRead("#dirPath#schemas/user/user.xsd") }
	],
	samples=[
		{format="json", description="The basic user information will be returned in a flat object.", body=fileRead("#dirPath#samples/user/user.json")},
		{format="json", description="If the requested user is not found, or some other error has occurred, the resopnse will be like the following.", body=fileRead("#dirPath#samples/user/failure.json")}
	]
}

As you can see, you can define multiple declarations for each category. Each containing:

Programmatic DSL

A part from the implicit configuration, you can use our more versatile and clean programmatic DSL to configure your relaxed resources. The Relax DSL configuration object which is mixed into a simple Relax CFC Definition Object so you can use all the methods in this CFC to define RESTful web services. All functions can be concatenated to create a nice programmatic DSL.

service()

The relaxed service information. From here you will define the RESTful service endpoints, extension detection, valid formats, and more.

Arguments

defaultMethod()

Define a default HTTP method for a resource

Arguments

placeholder()

Add a placeholder to a resource

Arguments

schema()

Append a schema to a resource

Arguments

globalHeader()

Add a global header to the relax definition

Arguments

resource()

Add a new resource to the API definition, you can then concatenate more methods to the same resource: methods(),description(),header(),parameter(),placeholder(),schema(),sample()

Arguments

setPlaceHolders()

Set all the required placeholders of a resource

Arguments

sample()

Append a sample to a resource

Arguments

setParams()

Set all the required parameters of a resource

Arguments

globalParam()

Add a global parameter to the relax definition

Arguments

methods()

Add methods to a resource

Arguments

description()

Add a description to a resource

Arguments

defaultFormat()

Define a default return format for a resource

Arguments

setHeaders()

Set all the required headers of a resource

Arguments

header()

Add a header to a resource

Arguments

param()

Add a param to a resource

Arguments

Screenshots

RelaxLogs

The RelaxLogs section of the module is a nice log viewer that can tap to any table that was used or has the columns the LogBox Database Appender talks to. This is a great way to monitor your service log entries and report on them. So let's configure it:

LogBox Service Configuration

In order for our RelaxLogs to be able to communicate with your log tables you must enable logging in your application. This is done via LogBox–which is already in all ColdBox applications. To get things working you simply need to add a Appender (or destination) that will store the log entries in a database. If you are not building a ColdBox application–which you should–then have no worries because LogBox can work with any ColdFusion application or framework. Logging your ReSTful service in this manor is helpful as it allows you to maintain a history of your ReSTful service's status and operation. All production sites are recommended to follow these steps:

1. LogBox Setup

The following is the programmatic approach to adding the LogBox Database Appender so you can log entries to the database of your choice.

//LogBox DSL
logBox = {
    // Define Appenders
    appenders = {
        // A simple tracer appender
        coldboxTracer = { class="coldbox.system.logging.appenders.ColdboxTracerAppender" },
        // Database Appender Registration
        dbAppender = {
            class="coldbox.system.logging.appenders.DBAppender",
            properties = {
                // The datasource to connect to
                dsn = "relax", 
                // The table to log to
                table="api_logs", 
                // If the table does not exist, then create it
                autocreate=true, 
                // The type to use for long text inserting.
                textDBType="longtext"
            }
        }
    },
    // Root Logger
    root = { levelmax="INFO", appenders="coldboxTracer" }
};

Once you define the Appender in your configuration, LogBox can send messages to this destination. We suggest your review your LogBox skills before anything to understand how Loggers work and how you can even declare categories that point to specific destinations.

2. Custom LogBox Category

We suggest you create a special LogBox category and assign it this Database Appender destination. This will provide you with the ability that only log messages with this category will go to your database. We mostly do this to not overpopulate our DB with other kinds of log messages.

//LogBox DSL
logBox = {
    // Define Appenders
    appenders = {
        // A simple tracer appender
        coldboxTracer = { class="coldbox.system.logging.appenders.ColdboxTracerAppender" },
        // Database Appender Registration
        dbAppender = {
            class="coldbox.system.logging.appenders.DBAppender",
            properties = {
                // The datasource to connect to
                dsn = "relax", 
                // The table to log to
                table="api_logs", 
                // If the table does not exist, then create it
                autocreate=true, 
                // The type to use for long text inserting.
                textDBType="longtext"
            }
        }
    },
    // Root Logger
    root = { levelmax="INFO", appenders="coldboxTracer" },
     
    // Custom LogBox Category
    categories = {
        myRestService = { levelMax="DEBUG", appenders="dbAppender"}
    }
};

3. Logger Injection

Once this is done, we can inject our logger objects that LogBox provides into our handlers or domain objects that will send messages to our log tables. This is done via ColdBox's WireBox Dependency Injection engine and our Autowire DSL. The important part of this section is that we inject the logger with the category we setup in our configuration.

component name="Awesome REST Handler"{
 
    // inject correct logger
    property name="logger" inject="logbox:logger:myRestService";
     
     
    // log any call to any event in this awesome REST handler
    function preHandler(event,action){
        if( logger.canDebug() ){
            logger.debug("A request to relax/logs/help/ was made.", getHTTPRequestData() );
        }
    }
 
}

As you can see we first check if we can debug and then send a debug message to LogBox. The second argument of any Logger method can be any variable (simple or complex) that we would like to log. In our case, since it is a ReSTful service, we send the request data out for logging. Good for debugging.

4. Go Relax!

You did the hard work, now go relax! You can now configure the relaxLogs structure in the modules configuration (as shown before) and you are ready to roll.

Download in other Formats:
Markup | HTML | Word

Comments (5)

Add Comment

Joseph Lamoree said

at 04:44:30 PM 25-Apr-2011

What's the best way to document structured data returned after a resource request? Regardless of format detection, the response will have a logical data structure that I'd like to document. It would be super awesome if I could add my JSON Schemas to the Relax DSL.

Luis Majano said

at 06:25:35 PM 25-Apr-2011

Jason, can you expand on this?

Joseph Lamoree said

at 06:19:07 PM 26-Apr-2011

For example, the response format of /v1/users/:username is like this: http://pastebin.com/qyWVhK7n And here are successful and unsuccessful response examples: http://pastebin.com/S6GtQFhn I'd like to be able to have that information in my Relax documentation somehow.

Luis Majano said

at 07:16:57 PM 26-Apr-2011

Hmm very interesting, can you follow up on this conversation in our google group to get more ideas

Joseph Lamoree said

at 01:39:40 PM 28-Apr-2011

I posted to the ColdBox group here: https://groups.google.com/forum/#!topic/coldbox/baS9WfHUqS8