Index of API Methods

This page is an alphabetical listing of all methods that Taffy exposes for you to use in your APIs. If a method is not included here, you should consider it un-documented, and as such it may change or be renamed at any time without notice. I will make a conscious effort not to break or rename any documented functions, though they may change with a major version if it is an improvement to the framework.

• Application.cfc Methods
  • applicationStartEvent
  • configureTaffy
  • requestStartEvent
  • registerMimeType
  • setDashboardKey
  • setDebugKey
  • setDefaultMime
  • setDefaultRepresentationClass
  • setReloadKey
  • setReloadPassword
• Resource CFC Methods
  • noData
  • representationOf
  • withStatus

Application.cfc Methods

The following methods are available in your Application.cfc:

applicationStartEvent()

Use it inside: Application.cfc Parameters: (none)

Since the framework takes over the onApplicationStart event of Application.cfc, it also exposes this methdod as a way for you to add logic to be executed when the event occurs. applicationStartEvent is called by onApplicationStart before the framework is initialized. Your Application.cfc should NOT implement onApplicationStart, and should instead use applicationStartEvent.

configureTaffy()

Use it inside: Application.cfc Parameters: (none)

This is a special method called by the framework during initialization to get your APIs configuration. You must implement this method in your Application.cfc for the framework to work correctly. All configuration methods should be used inside your implementation of configureTaffy, if you intend to use them.

requestStartEvent()

Use it inside: Application.cfc Parameters: (none)

Since the framework takes over the onRequestStart event of Application.cfc, it also exposes this methdod as a way for you to add logic to be executed when the event occurs. requestStartEvent is called by onRequestStart after the framework is re-initialized (if requested). Your Application.cfc should NOT implement onRequestStart, and should instead use requestStartEvent.

registerMimeType(string extension, string mimeType)

Use it inside: configureTaffy Parameters:

• extension (string) - The url-extension that will invoke this mime type. (e.g. "xml" or "json")
• mimeType (string) - The mime type that should be set into the http headers when the corresponding extension is requested. (e.g. "application/xml" or "application/json")

Each mime type that your API is capable of returning needs to be registered with the framework, and the configureTaffy method is the most efficient place to do so.

Because the framework implements JSON by default, the JSON ("application/json") mime type is already registered, and you do not have to re-register it. (You can if you like, though. It won't hurt anything.)

setDashboardKey(string keyName)

Use it inside: configureTaffy Parameters:

• keyName (string) - Name of the url parameter that displays the dashboard. Default value is "dashboard".

The dashboard currently displays a ColdFusion dump of your current Taffy configuration, and any cached resource location information, as well as a handy link to reload the API. I intend to add more information here over time.

setDebugKey(string keyName)

Use it inside: configureTaffy Parameters:

• keyName (string) - Name of the url parameter that enables CF Debug Output. (e.g. "debug")

Sometimes it's useful to see ColdFusion's debug output in the results of your API requests during testing. For that reason, you can include this query string parameter to enable debugging on a per-request basis.

If you do not change it, the default value is, "debug".

setDefaultMime(string DefaultMimeType)

Use it inside: configureTaffy Parameters:

• DefaultMimeType (string) - The mime type that should be returned when none is specified by the consumer. (e.g. "json")

It is important to note the difference between the mime type and extension. Here, the extension is expected because of its brevity. While the mime type to be returned is "application/json", you should pass the string "json" to the function. If, for example, you registered the mime type of "xml" as "application/xml" (using registerMimeType), and you wanted XML to be the default format, you would pass the string "xml" to the setDefaultMime function; and it could be specified on the url by appending ".xml" to the URI, before any query string parameters, like so:

/artists.xml?city=Philadelphia

If not implemented, the framework default mime type is JSON ("application/json").

setDefaultRepresentationClass(string customClassDotPath)

Use it inside: configureTaffy Parameters:

• customClassDotPath (string) - Dot-notation path to the CFC to be used by default.

When you change the default Representation Class, all responses will use your custom default class, unless you specifically override that request, using the (optional) second parameter to the representationOf function.

setReloadKey(string keyName)

Use it inside: configureTaffy Parameters:

• keyName (string) - Name of the url parameter that requests the framework to be reloaded. (e.g. "reload")

Used in combination with the reload password (see: setReloadPassword), the framework will re-initialize itself. During re-initialization, all configuration settings are re-applied and all cached objects are cleared and reloaded. If the value of the key does not match the reload password, a reload will not be performed. This allows you to set a secret password to restrict control of reloading your API to trusted parties.

If you do not change it, the default value is "reload".

setReloadPassword(string Password)

Use it inside: configureTaffy Parameters:

• keyName (string) - Accepted value of the url parameter that requests the framework to be reloaded. (e.g. "true")

Used in combination with the reload key (see: setReloadKey), the framework will re-initialize itself. During re-initialization, all configuration settings are re-applied and all cached objects are cleared and reloaded. If the value of the key does not match the reload password, a reload will not be performed. This allows you to set a secret password to restrict control of reloading your API to trusted parties.

If you do not change it, the default value is, "true".

Resource CFC Methods:

Resource CFCs extend taffy.core.resource. The following methods are available inside each of your Resource CFCs:

noData()

Use it inside: get, post, put, and delete methods inside your Resource CFCs. Parameters: (none)

This method allows you to specify that there is no data to be returned for the current request. Generally, you would use it in conjunction with the withStatus method to set a specific return status for the request. For example, if the requested resource doesn't exist, you could return a 404 error like so:

return noData().withStatus(404);

representationOf(any data, [string customRepresentationClass])

Use it inside: get, post, put, and delete methods inside your Resource CFCs. Parameters:

• data (any) - The data to return to the consumer.
• optional customRepresentationClass (string) - Dot-notation path to a custom CFC that will serialize your results. Defaults to included generic serializer which supports JSON.

Data can be of any type, including complex data types like queries, structures, and arrays, as long as the serializer knows how to serialize them. For more information on using a custom representation class, see Using a custom Representation Class.

withStatus(numeric statusCode)

Use it inside: get, post, put, and delete methods inside your Resource CFCs. Parameters:

• statusCode (numeric) - the HTTP Status Code to return to the consumer.

This special method may only be used in conjunction with noData or representationOf. It sets the HTTP Status Code of the return.

If you do not specify a return status code, Taffy will always return status code 200 (OK) by default.