Config Details

When you create an instance of Relaxation, the constructor takes an argument of "Config".

var Relaxation = new com.Relaxation.Relaxation( "./RestConfig.json.cfm" );

The Config argument is of type "any" and can be specified in the following ways.

• ColdFusion Structure
• String of JSON
• Relative path to a JSON config file
• Absolute path to a JSON config file

Note: If you learn better by example, you may want to jump straight to the example config.

"RequestPatterns"

"RequestPatterns" is at the top level of the config object. This is where you define the URI patterns your API will handle.

Each URI handler is defined as follows:

• {URI Pattern} (e.g. "/product/{ProductID}")
  • {Verb} (e.g. GET)
    • Bean (e.g. "ProductService")
    • Method (e.g. "getProductByID")
    • CacheHeaderSeconds (Optional) (e.g. 60)
    • DefaultArguments (Optional)
      • Arg1 (e.g. "Active": 1)
      • Arg2 (e.g. "Status": "Available")
      • ...
    • WrapSimpleValues (Optional)
      • enabled (true|false)
      • objectProperty (e.g. "result")

URI Pattern

The key names in the "RequestPatterns" object are URI patterns (e.g. "/product/{ProductID}"). When building URI patterns, you may use tokens surrounded by {}s.

Token handling example:

1. An HTTP client makes a GET request for "/rest/product/123".
2. It is matched to the request pattern "/product/{ProductID}".
3. An argument is set named "ProductID" with the value "123".

Verb

Each URI pattern contains an object that has keys for the HTTP verbs it will support (e.g. GET, POST). Each verb contains an object with 2 required keys ("Bean", and "Method") and 2 optional keys ("DefaultArguments" and "CacheHeaderSeconds").

Bean is the value that will be passed to getBean(Bean).
Method is the method that will be called on the "Bean".
DefaultArguments (Optional) will be used as defaults for the argument collection that will be provided when your method is called. CacheHeaderSeconds (Optional) is the number of seconds you would like to allow HTTP clients to cache a GET request. This should only be set for "GET".
WrapSimpleValues (Optional) will control the "wrap simple values" behavior of the framework. (See WrapSimpleValues.)

"WrapSimpleValues"

Because simple values do not serialize to valid JSON, Relaxation provides a "WrapSimpleValues" config property. This structure defines what the framework does when the result of calling a method on a service is a simple value. "WrapSimpleValues" can be set at the top level of the config object. It can also be set at the "verb" level of the "RequestPatterns".

The following is the default "WrapSimpleValues" config.

"WrapSimpleValues" = {
	"enabled" = true
	,"objectProperty" = "result"
}

/* Which produces the following if your service returned a boolean true. */
{"result": true}

enabled will toggle the wrapper struct on or off for simple values.
objectProperty will determine the property name in the returned object for simple values.

The framework will cascade the defaults into your config. Then, it will cascade the config defaults down onto each verb. You may set either or both properties at either level. For example, you may disable the setting at the top level, but, then turn it on for GET requests for specific resources. Another example would be to configure your default objectProperty to be "result" but, then override it to "newID" for a POST to a collection.

Example Config

{
	"WrapSimpleValues": {
		"objectProperty": "response"
	}
	,"RequestPatterns": {
		"/product": {
			"GET": {
				"Bean": "ProductService"
				,"Method": "getAllProducts"
			}
			,"POST": {
				"Bean": "ProductService"
				,"Method": "addProduct"
				,"WrapSimpleValues": {
					"objectProperty": "newID"
				}
			}
		}
		,"/product/all-active": {
			"GET": {
				"Bean": "ProductService"
				,"Method": "getAllProducts"
				,"DefaultArguments": {
					"Active": 1
					,"Status": "Available"
				}
			}
		}
		,"/product/colors": {
			"GET": {
				"Bean": "ProductService"
				,"Method": "getProductColors"
			}
		}
		,"/product/{ProductID}": {
			"GET": {
				"Bean": "ProductService"
				,"Method": "getProductByID"
			}
			,"PUT": {
				"Bean": "ProductService"
				,"Method": "saveProduct"
			}
		}
		,"/product/{ProductID}/colors": {
			"GET": {
				"Bean": "ProductService"
				,"Method": "getProductColorsByProduct"
			}
		}
	}
}