Flex to REST CFC Endpoint
Sean Corfield recently published a ColdFusion Component (CFC) that can act as a REST endpoint. I had read a previous post by Sean that talked about this component, and asked him if I could take a look at it. With certain disclosures in mind, Sean let me play with the component, and while he’s using it for Java-to-CF connectivity, I’m using it for Flex-to-CF connectivity.
You might be wondering why one you would expose CF to Flex as REST if Flex can talk to CF directly already in a number of ways (including the more efficient remoting). For me it wasn’t so much about Flex as a consumer, that’s just what I had on hand, and the technology with which I am most familiar. The potential side effect is that Flex can consume my server-side application API in the same fashion as everything else.
Regardless of the potential value (or not), here’s a walk-through of a simple example using Sean’s CFC REST endpoint from Flex.
The first part is to have a CFC to call. I have a generic “Greeting” CFC that I use for simple tests/demonstrations. You can think of it as an OO “Hello World” that has a function for a “hello” greeting and a function for a “goodbye” greeting. Each function takes a single argument – the name of the person to greet. The code for the CFC is as follows, and Sean’s “endpoint.cfc” is in the same directory.
<cfcomponent name=”Greeting” displayname=”Greeting” hint=”Generic greeting component for testing”>
<cffunction
name=”hello”
displayname=”hello”
hint=”Says hello to the provided user name”
access=”remote”
output=”false”
returntype=”string”>
<cfargument
name=”name”
displayName=”name”
type=”string”
hint=”The name of the user to greet”
required=”true” />
<cfreturn “Hello, ” & name & “!” />
</cffunction>
<cffunction
name=”goodbye”
displayname=”goodbye”
hint=”Says goodbye to the provided user name”
access=”remote”
output=”false”
returntype=”string”>
<cfargument
name=”name”
displayName=”name”
type=”string”
hint=”The name of the user to greet”
required=”true” />
<cfreturn “Goodbye, ” & name & “!” />
</cffunction>
</cfcomponent>
The Flex front-end to this component simply asks the user for a string, and expects that the value is a person’s name (though it can be anything). It gets interesting when the button to submit the values is clicked. In short what happens is that an HTTPService instance is used to POST XML content to the “endpoint.cfc”. When a response is returned, I simply display the value in an Alert control.
The HTTPService instance in this case is configured for the behavior the REST endpoint expects. It points to the CFC with a query string value of “rest”, and expects to make a POST request. I’ve also specified the content type to be XML rather than form name/value pairs. E4X makes handling the formatting of the request and, and the response itself a walk in the park.
<mx:HTTPService
id=”svcGreeting”
url=”http://[your_domain_here]/work/endpoint.cfc?method=rest”
method=”POST”
contentType=”application/xml”
resultFormat=”e4x”
useProxy=”false”
result=”doGreeting( event )” />
If you haven’t played around with E4X in ActionScript 3 yet, you’re really missing out. The ability to treat XML as a native data type gives you some very powerful functionality. In the case of this REST example, the CFC expects the name of the CFC to be invoked as the root XML packet node. That root node is also expected to have an operation attribute that specifies what function you’re going to call the on the designated CFC. Adding sub-nodes on the root packet, even deeply nested nodes, is just a matter of “dotting-down” and assigning a value.
Note that the XML object itself is provided to the argument of the service call. That XML object as a string will be the content data. Also notice the distinct lack of having to use quotes to establish nodes, or strange “child” methods/arrays. Yeah E4X!
public function doSend( event:MouseEvent ):void
{
var params:XML = new XML(
btnSend.enabled = false;
params.@operation = cmbGreeting.selectedLabel;
params.name.value = txtName.text;
svcGreeting.send( params );
}
In this example I’m passing a simple value and getting a simple value in return. I’ve since gone on to use Sean’s CFC for complex structures and arrays. In the case of a simple value I can use the descendant notation to pull the only “value” node in the response packet. For an array of structures, I use the same notation, but specify the “map” node, which is used for each structure.
btnSend.enabled = true;
Alert.show( svcGreeting.lastResult..value );
Sean’s REST endpoint CFC now allows Flex to talk to CF in the same fashion as would his original intention – Java. Others using PHP, Ruby, .NET or any other XML-capable language would also access the endpoint in the same fashion. It’s a really powerful means of exposing an entire CFC API in a consistent manner. The complete source for my example is attached to this post.