I googled everywhere for how to do this, and drew a complete blank. I had to fall on the mercy of a friendly Adobe engineer to help me get it working, so I thought I would knock together a quick article so if anyone else ever needs to do this, there's something for Google to find.
Firstly, I gotta say that on the whole I probably would not create a RESTful web service which accepts a complex value... it seems to make more sense to me to work with simply types, and perhaps reflect any complex nature using collections of simple-value fields, or JSON or something. Still: I had this specific requirement which was out of my hands, so I needed to make it work.
Just before I get onto the code, I'll dwell on this. I read the docs for "RESTful Web Services in ColdFusion", which say this:
First on the "REST services and data interchange formats" page:
REST services in ColdFusion can be represented in XML or JSON formats for transmitting over the web. ColdFusion takes care of the serialization/deserialization of the ColdFusion data types used in the services to XML or JSON implicitly.OK, so based on this, I can pass a serialised struct into a method which expects a struct, and it should work. Cool.
A function that is REST-enabled can take the following ColdFusion data types as arguments: query, struct, CFC type, array, array of CFCs, XML, string, numeric, boolean, date, and binary (for XML).
ColdFusion serializes data to pre-defined formats of XML and JSON. Similarly, ColdFusion deserializes the body only if the body is in the format defined by ColdFusion.
Then on the "JSON serialization and REST services" page:
So the key bits here are these:Deserialization specifications
- The content of the request is in a predefined format specified by ColdFusion.
- The content type of the request is text/JSON, application/JSON, or text/plain.
- A function in the service consumes the MIME type of the request.
- cfargument does not have the attributes restargsource and restargname specified.
- cfargument type is ColdFusion supported data type other than binary or CFC definition.
- Only one argument has no restAargSource attribute specified.
- The whole body of the request is deserialized to the argument type.
- Cyclic behavior is unsupported. But in the case of cyclic arrays, you might see the deserialized array published, but not giving expected output.
- I can pass a struct;
- I need to pass it as JSON;
- the function I'm passing it to needs to consume JSON;
- I don't have any of ColdFusion's special REST parameters on the argument definition;
- as above, I need to specify the argument as a struct;
- I need to pass the actual struct in the request body.
// Application.cfc
component {
this.name = "testSerialiser03";
public void function onApplicationStart(){
restInitApplication(expandPath("../components"), "components");
}
}
// components/TestSerialiser.cfc
component rest=true restPath="testserialiser" {
remote struct function echoStruct(required struct data ) httpmethod="post" restpath="echoStruct" consumes="application/JSON" produces="application/JSON" {
data.uid = createUuid();
return data;
}
}
<!--- test.cfm --->
<cfset two = {id=2, en="two", ma="rua"}>
<cfdump var="#two#" label="Original">
<cfhttp method="post" url="http://#CGI.http_host#/rest/components/testserialiser/echoStruct/" result="response">
<cfhttpparam type="header" name="Content-Type" value="application/JSON">
<cfhttpparam type="body" value="#serializeJson(two)#">
</cfhttp>
<cfdump var="#response#" label="HTTP response">
<cfset echoed = deserializeJson(response.filecontent)>
<cfdump var="#echoed#" label="Result">
| Original - struct | |
|---|---|
| EN | two |
| ID | 2 |
| MA | rua |
| HTTP Response - struct | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Charset | [empty string] | ||||||||||||||||||||
| ErrorDetail | [empty string] | ||||||||||||||||||||
| Filecontent | {"EN":"two","UID":"CDA59632-EE5B-60E4-BF994402F7130EB4","ID":2,"MA":"rua"} | ||||||||||||||||||||
| Header | HTTP/1.1 200 OK Server: Apache-Coyote/1.1 CF_TOMCAT_REUSE_THIS_CONNECTION: FALSE Content-Type: application/JSON Content-Length: 74 Date: Fri, 31 May 2013 14:21:28 GMT Connection: close | ||||||||||||||||||||
| Mimetype | application/json | ||||||||||||||||||||
| Responseheader |
| ||||||||||||||||||||
| Statuscode | 200 OK | ||||||||||||||||||||
| Text | YES | ||||||||||||||||||||
| Result - struct | |
|---|---|
| EN | two |
| ID | 2 |
| MA | rua |
| UID | CDA59632-EE5B-60E4-BF994402F7130EB4 |
So that's a silly demonstration, but it demonstrates the point.
OK, so why did I have to rely on a friendly Adobe engineer to help me out with this... all I needed to do is to follow the instructions, right? Yeah, well: had I followed all the instructions properly, it'd've worked first time.
However I overlooked this bit:
The content type of the request is text/JSON, application/JSON, or text/plain.
<cfhttp method="post" url="http://#CGI.http_host#/rest/components/testserialiser/echoStruct/" result="response"> <cfhttpparam type="header" name="Content-Type" value="application/JSON"> <cfhttpparam type="body" value="#serializeJson(two)#"> </cfhttp>
Basically I forgot to put that <cfhttpparam> in. Doh! I tried about one million different things to try to get it to go without that, and it just cacked out, giving me one of these:
HTTP/1.1 415 Unsupported Media Type Server: Apache-Coyote/1.1 Content-Type: application/JSON
or:
Application components could not be initialized.
Reason: Missing dependency for method public java.util.Map testing.rest.components.TestSerialiser.echoStructViaUrl(java.util.Map) throws coldfusion.xml.rpc.CFCInvocationException at parameter at index 0
depending on what I was doing.
So that's that.
Hopefully I've included enough content in here that if someone needs to google this stuff up, they'll find this example.
The upside for me is that now I've read a lot more about ColdFusion RESTful web services, and have practised a lot of different bits of functionality they offer. So that's good!
Righto.
--
Adam
