Skip to content

QuickStart Guide

Jump to bottom
Chris Phillips edited this page Dec 2, 2021 · 26 revisions

First, download Relaxation. You can download version 1.5.0 here. Or you can download specific versions here. Unzip the archive.

Setup

Inside of the archive is a folder called "Relaxation" containing a "Relaxation.cfc". Put that folder wherever you want. The example below uses "/com".

Choose what the root path of your API will be. Some common choices are "/rest" or "/api". Create a folder in your web root named whatever you choose (e.g. "{wwwroot}/rest"). You will need a .cfm in that folder to route requests to. I recommend "index.cfm". However, you can use whatever you like. It just has to be a real file in the folder that you want to prefix your REST paths with.

Request Pattern Configuration

Create a file somewhere to hold your Relaxation config file (e.g. "{wwwroot}/rest/RestConfig.json.cfm"). Put the following example code in it.

{
	"RequestPatterns": {
		"/test": {
			"GET": {
				"Bean": "YOURBEANNAME"
				,"Method": "TESTMETHOD"
			}
		}
	}
}

To get started, pick one of your beans that has a method that can be called without any arguments that returns something. Enter your bean and method name in the config file and save it.

Initialization

Place the following code somewhere in your application initialization code. I recommend onApplicationStart. However, you may put it wherever you like as long as it's initialized before you need it.

/*
 * The constructor arg can be a relative or absolute path to a JSON config file or a structure.
 * setBeanFactory() accepts any component that has a "getBean(BeanName)" method.
 **/
var Relaxation = new com.Relaxation.Relaxation( "./RestConfig.json.cfm" );
Relaxation.setBeanFactory( application.BeanFactory );
application.REST = Relaxation;

Request Handling

Place the following code somewhere. I recommend in the onRequest method in the Application.cfc in the base bath of your REST api (e.g. "{wwwroot}/rest/Application.cfc"). However, you may put it wherever you like.

application.REST.handleRequest()

You should now be able to hit, "/{your rest folder}/index.cfm/test". So, if you put your rest files in a folder called "rest", then you should be able to hit "/rest/index.cfm/test". When you hit that URL, you should see JSON. I recommend installing a browser plugin like JSONView so that the json response is pretty and readable.

Next Steps

If you plan to use Relaxation to build a REST API, you might be interested in the following topics.

Clone this wiki locally