Using Positional URL Arguments When Invoking A ColdFusion Web Service
A couple of months ago, I was super excited to find out that you could use an ArgumentCollection URL parameter when invoking a ColdFusion web service. Yesterday, I took that excitement up a notch when I discovered that this same approach to ColdFusion web services works with positional arguments. And, not only does the ArgumentCollection URL parameter work with positional arguments, each positional argument can, alternatively, be passed through independently.
To demonstrate this functionality, I have set up a very simple ColdFusion web service - Greeting.cfc. This web service just takes two Named arguments and builds a response. When we invoke this web service, we will be using ordered / positional arguments in lieu of named arguments.
Greeting.cfc
<cfcomponent
output="false"
hint="I provide a simple greeting method.">
<cffunction
name="sayHello"
access="remote"
returntype="string"
returnformat="json"
output="false"
hint="I say something to the given person.">
<!--- Define arguments. --->
<cfargument
name="name"
type="string"
required="true"
hint="I am the person we are talking to."
/>
<cfargument
name="compliment"
type="string"
required="false"
hint="I am the optional compliment."
/>
<!--- Check to see if the compliment exists. --->
<cfif structKeyExists( arguments, "compliment" )>
<!--- Return just the hello with a compliment. --->
<cfreturn "Hello, #arguments.name#, you are #arguments.compliment#." />
<cfelse>
<!--- Return just the hello. --->
<cfreturn "Hello, #arguments.name#." />
</cfif>
</cffunction>
</cfcomponent>
Pretty straightforward stuff. Now, let's test it. In the following demo, I am going to invoke the above ColdFusion web service using positional arguments. When doing this, I am going to use two different approaches: the first approach will pass the positional arguments through as a single serialized ArgumentCollection value; the second approach will pass the positional arguments through as individual URL parameters.
<!--- Build the URL for the web service. --->
<cfset webServiceUrl = (
"http://" &
cgi.server_name &
getDirectoryFromPath( cgi.script_name ) &
"Greeting.cfc"
) />
<!---
Build the arguments collection that we are going to use to
invoke the Greeting.cfc.
--->
<cfset webServiceArguments = {} />
<cfset webServiceArguments[ 1 ] = "Katie" />
<cfset webServiceArguments[ 2 ] = "looking super adorable" />
<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->
<!---
Invoke the web service. In this pass, we're going to use the
above web service arguments structure and pass it through as
a serialized "argumentCollection" URL variable.
--->
<cfhttp
result="get"
method="get"
url="#webServiceUrl#">
<!--- The method we are invoking. --->
<cfhttpparam
type="url"
name="method"
value="sayHello"
/>
<!--- Serialize the argument collection as JSON. --->
<cfhttpparam
type="url"
name="argumentCollection"
value="#serializeJSON( webServiceArguments )#"
/>
</cfhttp>
<!--- Output the response. --->
<cfoutput>
<strong>ArgumentCollection Response:</strong>
#deserializeJSON( get.fileContent )#
</cfoutput>
<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->
<br />
<br />
<!--- ----------------------------------------------------- --->
<!--- ----------------------------------------------------- --->
<!---
Invoke the web service again. This time, however, rather than
passing in an argumentCollection URL variable, we are going to
pass in individual, ordered arguments as separate URL variables.
--->
<cfhttp
result="get"
method="get"
url="#webServiceUrl#">
<!--- The method we are invoking. --->
<cfhttpparam
type="url"
name="method"
value="sayHello"
/>
<!---
Pass first argument. Notice that the NAME of the url
variable is the index of the positional argument.
--->
<cfhttpparam
type="url"
name="1"
value="#webServiceArguments[ 1 ]#"
/>
<!---
Pass second argument. Notice that the NAME of the url
variable is the index of the positional argument.
--->
<cfhttpparam
type="url"
name="2"
value="#webServiceArguments[ 2 ]#"
/>
</cfhttp>
<!--- Output the response. --->
<cfoutput>
<strong>Ordered Argument Response:</strong>
#deserializeJSON( get.fileContent )#
</cfoutput>
When we run the above code, we get the following output:
ArgumentCollection Response: Hello, Katie, you are looking super adorable.
Ordered Argument Response: Hello, Katie, you are looking super adorable.
This works in both ColdFusion 8 and ColdFusion 9 (NOTE: both of these probably have updaters installed). And, just so you know that there's no false correlation of behavior taking place, let's try switching the order of the parameters:
<cfset webServiceArguments = {} />
<cfset webServiceArguments[ 2 ] = "Katie" />
<cfset webServiceArguments[ 1 ] = "looking super adorable" />
This time, when we invoke the ColdFusion web service (in both CF8 and CF9), we get the following output:
ArgumentCollection Response: Hello, looking super adorable, you are Katie.
Ordered Argument Response: Hello, looking super adorable, you are Katie.
As you can see, ColdFusion is clearly honoring the defined position of the URL parameters, both in ArgumentCollection format and in individual parameter format. This is awesome!
NOTE: This works for both GET and POST methods.
What If My Web Service Doesn't Have CFArgument Tags
As I have demonstrated before, using positional arguments in ColdFusion can get tricky, especially across different versions of ColdFusion. As I have shown above, the URL-based, positional argument approach is consistent in ColdFusion 8 and ColdFusion 9 when you use CFArgument tags. If you do not use CFArgument tags, however, inconsistencies do pop up. If I were to strip out my CFArgument tags and use the following CFReturn statement (within my web service):
<cfreturn "Hello, #arguments[ 1 ]#, you are #arguments[ 2 ]#." />
... I would get the following output when using positional arguments in a ColdFusion 8 web service:
ArgumentCollection Response: Hello, Katie, you are looking super adorable.
Ordered Argument Response: Hello, Katie, you are looking super adorable.
... and I would get the following output when using positional arguments in a ColdFusion 9 web service:
ArgumentCollection Response: Hello, looking super adorable, you are Katie.
Ordered Argument Response: Hello, looking super adorable, you are Katie.
As you can see, ColdFusion 9 fails to adhere to the stated index of the given positional arguments. The take away: always use CFArgument tags. Of course, that should be pretty obvious in general. CFArgument tags allow for self-documenting code; and, other than some outlier situations involving a variable-number of arguments, I can't see any valid, rational, defendable reason for not using CFArgument tags.
One of ColdFusion's most powerful (and most subtle) features is its ability to invoke methods using both named and positional arguments. I have made extensive use of this within my ColdFusion applications. However, I am thrilled to learn that this kind of invocation duality can exist when communication with a 3rd party application through the use of ColdFusion web services. This definitely opens the door for some interesting interactions.
Want to use code from this post? Check out the license.
Reader Comments