REST enhancements in ColdFusion (2018 release)

In the 2016 and earlier versions of ColdFusion, after developing a REST service, you had to log in to the ColdFusion Administrator to register the REST application. Also, with every change in the app, you had to re-register/refresh the REST app in the Administrator. In addition, there were issues in reporting and logging of errors related to the CFCs.

In the 2018 release of ColdFusion, the following are supported:

• Toggling “Enable Developer Profile” in CF Administrator
• RESTPlay application to try out registered APIs
• Auto refresh of REST services (if trusted cache is off)
• Language changes (component as an argument, lifecycle methods)
• Easy error tracking and debugging
• Support for PATCH verb
• Custom REST path
• Auto-registering of the REST APIs (by accessing URL)

ColdFusion provides an application, REST Playground, located in webroot/ restplay , which you can launch in the browser. It’s a client to test your ColdFusion REST services.

To use the REST Playground app, enable the option Enable Developer Profile in Debugging and Logging > Developer Profile in the ColdFusion administrator.

In the browser bar, enter <hostname>:<port>/restplay. In REST Playground, you can add and manage your REST services, without involving the ColdFusion Administrator.

REST Playground pulls the resources from the swagger docs and lists the resources. These are refreshed when there is a change in the CFC method and the service is invoked.

A status code of 500 is sent to the client when there are any server runtime errors.

If there are any compile time errors, they are shown when trying to access the service, or when refreshing the application (or even clicking on the application).

Sending the Response Status Code as 401 when the developer profile is disabled on the server when REST Playground tries to access the services.

Add an application in REST Playground

After you create a REST application, add the application using the REST Playground interface. Launch REST Playground (localhost:8500/restplay), and click +, as shown below:

After clicking the button, enter the details in the following dialog:

When you click Register, your REST app gets registered and appears as below:

Example: GET

In the example Artapp  application, to retrieve the details of a user, pass the  value for {id} in the URL, as shown below:

After clicking Send, you get the following response:

{

    "price": 13900,

    "id": 2,

    "name": "Michael"

}

Example: POST

Depending on the parameters defined, you can issue a POST request, as shown below:

If the parameters are defined to be passed as headers, then insert the parameters in the header section, as shown below:

Click Send to insert the record in the database.

Update REST path

In the REST Services section in Data and Services in the ColdFusion Administrator, we have added the option to add or update the REST path. The default value is rest.

Enable developer profile

To use the REST Playground, you can enable the option Developer Profile, while installing ColdFusion. Alternatively, after installation, enable the setting Enable Developer Profile in Debugging & Logging > Developer Profile.

This option is introduced in ColdFusion (2018 release) so that the REST  Playground app only functions in the Developer profile, not in the Production profile, or any other profile, for obvious security reasons.

Auto refresh of REST CFCs

Any change to the REST CFCs are reflected immediately on REST request, similar to the behavior of any cfm/cfc.

To reload the CFC or to load from cache is dependent on the server setting Trusted Cache (Server Settings > Caching). The same applies to REST CFCs as well.

Language changes

Support for REST functions with component as argument

When the argument is component, the REST request body must send the corresponding JSON object.

student.cfc

restCompTest.cfc

REST functions

You can skip writing access="remote" in REST functions. It is assumed inherently for all the REST enabled functions.

Support for onRESTRequest

Like OnCFCRequest, which is called on invoking CFC, onRESTRequest is introduced to be called on invoking REST URL. From the URL corresponding CFC, Method & Arguments are derived and passed to the function.

Change in behavior of restSetResponse

In previous ColdFusion versions, the response set in restSetResponse(response) used to be ignored if the return type was non-void.

In this release, the response set in restSetResponse(response) is always considered.

When the same function is used as a normal function (non-REST), it sends the response set in the return statement and in case of a REST call, the response returned using the return statement is ignored.

Easy debugging and logging

Like all cfm / cfc error messages, you can see the full stack trace when there are errors. You can also see the line number where there is an error.

Compile time/run-time errors are shown as html response with full stack trace of the error.

Support for PATCH verb

For PATCH support, there must be a GET resource with same resource path as PATCH resource. This is required to fetch the corresponding object on which PATCH must be applied. The GET resource must return the Object on which Patch must be applied, while PATCH resource Patches the value.

Both the operations are merged and the result is passed on the PATCH method as an argument, where you can control what you want to write in the function with the patched object.

Example of PATCH

The Patch to be posted is in the format as shown below:

Auto register REST applications

To auto- register a REST application, access the application by specifying the webroot path from the browser.

You require a REST-enabled cfc , Application.cfc, and any cfm page (say index.cfm) in a folder. When you access the cfm page (from the browser), all the REST services in the folder and the subfolders get registered.

The Application.cfc needs to have this.name and at least one of the this.restSettings.*  (for example, this.restSettings.restEnabled=true) variables.