User Guide Cancel

REST enhancements in ColdFusion (2018 release)

Last updated on Dec 22, 2021 05:34:19 AM GMT

ColdFusion User Guide
Introduction to ColdFusion
Adobe ColdFusion (2021 release)
Install ColdFusion
Use ColdFusion
Performance Monitoring Toolset
Use ColdFusion Builder
Coldfusion API Manager
Configure and administer ColdFusion
CFML Reference
1. Introduction to CFML Reference
2. Reserved words and variables
3. ColdFusion tags
  1. ColdFusion tags
  2. Tags in ColdFusion 10
  3. Tag summary
  4. Tags by function
  5. Tag changes since ColdFusion 5
  6. Tags a-b
  7. Tags c
  8. Tags d-e
  9. Tags f
  10. Tags g-h
  11. Tags i
  12. Tags j-l
  13. Tags m-o
  14. Tags p-q
  15. Tags r-s
  16. Tags t
  17. Tags u-z
4. ColdFusion functions
5. Ajax JavaScript functions
6. ColdFusion ActionScript functions
7. ColdFusion mobile functions
8. Application.cfc reference
9. Script functions implemented as CFCs
10. ColdFusion Flash Form style reference
11. ColdFusion event gateway reference
12. ColdFusion C++ CFX Reference
13. ColdFusion Java CFX reference
14. WDDX JavaScript Objects
Develop ColdFusion applications
1. Introducing ColdFusion
2. Changes in ColdFusion
3. Introduction to application development
4. The CFML programming language
5. Building blocks of ColdFusion applications
6. Develop CFML applications
7. Develop mobile applications
8. Access and use data
9. ColdFusion ORM
10. ColdFusion and HTML5
11. Flex and AIR integration in ColdFusion
12. Request and present information
13. Office file interoperability
14. ColdFusion portlets
15. Work with documents, charts, and reports
16. Use web elements and external objects
17. Use external resources

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:

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 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.

Enable Developer Profile option

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.

Legal Notices | Online Privacy Policy

REST enhancements in ColdFusion (2018 release)

REST Playground application

Add an application in REST Playground

Example: POST

Update REST path

Enable developer profile

Auto refresh of REST CFCs

Language changes

Support for REST functions with component as argument

REST functions

Support for onRESTRequest

Change in behavior of restSetResponse

Easy debugging and logging

Support for PATCH verb

Auto register REST applications

Ask the Community

Contact Us