Application path (Required)
Last updated on
22 Dec 2021
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)
REST Playground application
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.
Note:
Since REST Playground application is not meant for production, the application is accessible only through an internal server (not accessible through a web server).
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:
|
|
The path to the folder that contains the REST-enabled CFCs. |
|
Host (Optional) |
Host name for the REST service. For example, localhost:8500. |
|
Service Mapping (Optional) |
Identifier for the REST application when calling the service. |
|
Set as default application (Optional) |
By setting the application as default, you can exclude the name of the application in the URL, when invoking the service. For a host, you can make only one application as default. |
When you click Register, your REST app gets registered and appears as below:
Note:
All REST services registered in the ColdFusion Administrator are readily available here and you do not have to re-register the apps.
Similarly, the apps you register using the REST Playground are available in the ColdFusion Administrator.
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.
Note:
It is recommended to disable Developer profile for REST services that are in production.
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.
Note:
If you enable the Developer Profile option, the Trusted Cache option gets disabled.
Even when Developer Profile option is disabled, if you want to refresh REST services on modifications of the CFC, you can still disable Trusted Cache.
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
component hint="This is a student cfc"
{
property name="name" type="string" displayname="name" hint="name of student";
property name="age" type="numeric" displayname="age" hint="age of student";
}
restCompTest.cfc
component restpath="student"{
remote any function addStudentPost(student st) httpmethod="POST" restpath="addStudent"
{
studentcomp.name = st.name;
studentcomp.age = st.age;
return studentcomp;
}
}
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.
<cffunction name="onRESTRequest" returntype="any" output="true">
<cfargument type="string" name="cfcname" required=true>
<cfargument type="string" name="method" required=true>
<cfargument type="struct" name="args" required=true>
<cflog text="onRESTRequest() Before">
<cfinvoke component = "#cfcname#" method = "#method#" argumentCollection = "#args#" returnVariable = "resultval">
<cflog text="onRESTRequest() After">
<cfreturn "#resultval#">
</cffunction>
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
component restpath="users" rest="true"
{
import student;
student = createobject("component","student");
student.name = "Joe";
student.age = 22;
remote any function patchuser(struct x) httpmethod="PATCH" restpath="patchuser"
{
//x is patched object
return x;
}
remote any function patchuserget() httpmethod="GET" restpath="patchuser"
{
return student;
}
}
The Patch to be posted is in the format as shown below:
[
{
"op" : "replace",
"path" : "/age",
"value" : "40"
}
]
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.