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/
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.
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:
Application path (Required) |
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 |
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
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:
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.
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.
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.
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";
}
component restpath="student"{
remote any function addStudentPost(student st) httpmethod="POST" restpath="addStudent"
{
studentcomp.name = st.name;
studentcomp.age = st.age;
return studentcomp;
}
}
You can skip writing access="remote" in REST functions. It is assumed inherently for all the REST enabled functions.
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>
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.
Like all
Compile time/run-time errors are shown as
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;
}
}
[
{
"op" : "replace",
"path" : "/age",
"value" : "40"
}
]
To auto-
You require a REST-enabled
The Application.cfc needs to have this.name and at least one of the this.restSettings.* (for example, this.restSettings.restEnabled=true) variables.
Twitter™ and Facebook posts are not covered under the terms of Creative Commons.