ColdFusion 10: RESTful WebServices in ColdFusion - Introduction

In ColdFusion 10, support for creating and publishing REST services has been added. The ColdFusion components can now be made available as REST services and these services can be consumed by various clients. REST stands for Representational State Transfer. It is an architectural style which is based on web standards and HTTP protocol. The idea here is to use HTTP protocol instead of complex mechanisms such as CORBA, RPC or SOAP to connect between the machines. In fact, the World Wide Web which is based on HTTP can be viewed as a REST based architecture.

REST Architectural principles:

A REST based application follows some architectural principles:

1. Resource Identification: In a REST based architecture everything is a resource. Each of these resources should be identified with a URI.  In ColdFusion, the functions are identified as resources, each of these resources can then be invoked using an URI.
2. Uniform and constrained interface: Every resource in a RESTful application should support HTTP common operations. The resources are manipulated with the HTTP protocol methods – GET, PUT, POST, DELETE.  In ColdFusion, the resources (functions) can be accessed via HTTP and each of these resource support the HTTP verbs. Depending on the verb specified in the request, the corresponding resource would be invoked.
3. Representation oriented: REST allows resources to have different representation – plain, html, xml, json etc. A client can request a specific representation via the HTTP protocol. HTTP provides a simple content-type negotiation protocol between the client and the server. For example, an AJAX application may need data in JSON format, where as a Java application may need it in XML format.
4. Stateless communication: In REST, the server doesn’t store the client session data. However, many techniques exist to exchange state information such as URI rewriting, cookies and hidden form fields. Also, for encryption REST can be used on top of HTTPS.

Getting Started with creating REST services

New attributes have been added to cfcomponent, cffunction and cfargument to aid in creating a REST service. Once a component is created it has to be registered with the Administrator and then it can be accessed via a HTTP request.

Creating a RESTful Web Service

cfcomponent:

As mentioned above, functions in a CFC are the resources and are invoked using a HTTP request. To mark a component as a REST service, attributes rest and restpath are provided. The attribute rest is a boolean attribute, if true the component is enabled as a REST service. This is an optional attribute if restpath is specified in cfcomponent tag. The restpath attribute is used to specify the path using which the REST service would be accessed. If restpath is not specified then the path to the CFC would be used in the URI to invoke the service.

<!--- component with attributes rest and restpath ---> <cfcomponent rest="true" restpath="/crudService"> <!--- handle GET request (httpmethod), take argument in restpath(restpath={customerID}), return query data in json format(produces=text/json) ---> <cffunction name="getHandlerJSON" access="remote" httpmethod="GET" restpath="{customerID}" returntype="query" produces="application/json"> <cfargument name="customerID" required="true" restargsource="Path" type="numeric"/> <cfset myQuery = queryNew("id,name", "Integer,varchar", [[1, "Sagar"], [2, "Ganatra"]])> <cfquery dbtype="query" name="resultQuery"> select * from myQuery where id = #arguments.customerID# </cfquery> <cfreturn resultQuery> </cffunction> </cfcomponent>

The function ‘getHandlerJSON’ handles a GET request and accepts an argument customerID. Notice the additional attributes in cffunction tag. The attribute ‘httpmethod’ is used to specify the type of request this function would handle (GET,POST etc,.). Attribute ‘restpath’ is used to specify the path that should be used in the URL, here the path is specified in curly braces as {customerID}. When this type of notation is used it indicates that a value is passed in the URL and the same has to be copied to the functions’ argument. Therefore the name of the argument is same as the one specified in restpath. There are different ways to pass arguments to a REST service, I’ll explain this in my next post.

Complex data types in ColdFusion such as Array, Query, Struct etc, will be serialized to either JSON or XML format. The produces attribute specifies the mime type to which the data returned by the function will be serialized to. There is also an attribute ‘consumes’ that specifies the mime type of data present in the request body.

Coming to the function arguments, the new attribute restargsource specifies the way in which arguments are passed to a rest service. In this example it is path which indicates the argument will passed in the URL path itself. The other possible values include Matrix, Header, Cookie, Form and Query.

Registering a REST Service

There are three ways in which REST services can be registered with the ColdFusion Administrator. You can use the Admin API (functions defined in extensions.cfc), the ColdFusion administrator console or use the restinitApplicaiton function. Using the Admin API and ColdFusion administrator console requires Administrator privileges and therefore would be available only to selected users. The function restInitApplication can be used to register a REST service and doesn’t require Administrator privileges.

restInitApplication(‘Absolute_path’,[‘Service mapping’])

The directory containing CFC files with with either rest=’true’ or with a restpath in the cfcomponent tag should be specified as the first argument. To identify the set of CFCs in a directory the Service mapping has to be provided. This is an optional fied, if there is an Applicaiton.cfc file present in the directory. In which case the Application name would be used to identify the REST services in the directory.

If any changes are made to any of the components in the registered directory then the corresponding service has to be refreshed. Again this can be done in the Administrator or a call to restInitApplication would refresh the registered service.

Accessing a REST service via HTTP

A RESTful Web service can be accessed either by using HTTP or HTTPS.  The URL to access a REST service in ColdFusion follows this format:

http://servername:port/context_path_j2ee/ rest/rest_application_name_or_serverMapping/restpath_or_componentPath/additionalrestPaths/params_ifany/

Here, the context_path_j2ee is applicable only if you have installed ColdFusion as J2EE on any of the Application servers. In which the context path would be cfusion (by default). However, this can be omitted on Standalone installation.

The string ‘rest’ in URL specifies that the request is for a REST service. ColdFusion has a servlet mapping for the same and would direct the request to the servlet that handles REST service. If there is a directory in the server webroot with the same name, then the servlet mapping has to be updated in web.xml file inside wwwroot\WEB-INF directory.

As mentioned earlier, while registering a REST service the application name specified in Applicaiton.cfc file would be used in the URL to access the REST service. If there is no Applicaiton.cfc then the specified service mapping would be used. To access a service specified in the component the restpath for the component has to be specified. However, if the restpath is not specified in the cfcomponent tag then the path to the CFC would be used in URL. Also, the functions defined in component can also have restpath defined and this has to be specified in the URL. If arguments are to be passed in the URL path then the same can also be specified.

In this example, the function ‘getHandlerJSON’, can be accessed using cfhttp:

<cfhttp url="http://localhost:8500/rest/restapp/crudService/1" result="restResult" method="GET"/>

Here restapp is the application name defined in Applicaiton.cfc file. /crudService is the restpath specified in the cfcomponent tag and the numeric 1 is the argument to the REST service. There are various ways in which arguments can be passed to a REST service, I’ll explain this in my next post.