Creating Webservices with Coldfusion

One could say that a tutorial isn't really needed to show someone how to create a webservice using Coldfusion because it's so easy. On one hand they are right, it is dead easy, but on the other hand there are some things you need to be mindful of when creating a webservice with Coldfusion.

It Couldn't Be Any Simpler

So how do you create a webservice in Coldfusion anyway? As the title above says, 'It couldn't be any simpler'. When you create a coldfusion component you generally create functions or methods in your component. If you want one of those methods or functions to be available as a webservice you simply change the access type to access="remote".

That's it, you've created a webservice in coldfusion simply by setting the access of the function to remote. This webservice will allow webservice consumers to get the result of two numbers added together, it really is as simple as that.

The Difficult Bit

With all that simplicity there must be one "got ya" right? Well here's the deal. Even though creating webservices are a snap in Coldfusion there are some things you need to worry about if you plan on providing your brilliant next webservice to the population at large. Coldfusion has some, how shall I say..., unique approaches to returning queries and structures in a webservice. Since a query and struct types don't exist in the SOAP specification consumers of your webservice will have problems figuring out what to do with them. You can avoide returning structures or queries in your webservices or you can use another approach.

CFProperty

Here is where things tend to get a little...difficult with webservices.
If you want to return a complex datatype for example a list of employee's. The query might return a bunch of rows that have the following columns: fname,lname,age,hiredate,empnumber. Naturally you would want to simply return the whole query but as I noted above it's not that simple if the consumer of your webservice is not using Coldfusion. You have to get a little creative. Enter the CFProperty Tag. This tag allows you to, through components, define a complex datatypes in the following manner.

What the heck? A practically empty component with only cfproperty tags?
You have basically defined a complex type you can then return an array of this complex type to the webservice consumer, it's is a lot easier to swallow than the querybean.

Your function would then look something like this:

<cffunction name="getEmployees" access="remote" returntype="employee[]">
      <cfset var returnarray = arrayNew(1)>
      <cfquery name="getemployees" datasource="#variables.dsn#">
         select fname,lname,age,hiredate,empnumber from employees
      </cfquery>
      <cfloop query="getemployees" >
       <cfobject component="employee" name="tempemp">
       <cfset tempemp.fnamee = getemployees.firstname>
       <cfset tempemp.lname = getemployees.lastname>
       <cfset tempemp.age=getemployees.age>
       <cfset tempemp.hiredate=getemployees.hiredate>
       <cfset tempemp.empnumber=getemployees.empnumber>
       <cfset temp = ArrayAppend(returnarray, tempemp)>
       </cfloop>
      <cfreturn returnarray/>
   </cffunction>

I admit that it's a bit more complicated and a bit more work but I guess there has to be a little complexity in exchange for making webservice creation so simple.

Where to go from here

Now that you know how to create webservices using Coldfusion as well as returning complex data types you can start creating webservices for all manner of useful things, perhaps even design your next application in a SOA approach.