Best way to code a QBE Restful method?

Question

I'm working on developing some web services using RESTeasy and Seam. One of the services I'd like to create is a Query by Example service.

I first tried to code it like this:

@GET
@Produces("application/xml")
@Consumes("application/xml")
@Path("/matching")
public MessageList getMatchingMessages(Message msg);

This, unfortunately, produced complications in the client:

[testng] [Parser] Running:
[testng]   C:\Users\bdw\workspace-shepherd\GPRI\test-build\testng-Test.xml
[testng] java.lang.RuntimeException: java.lang.ClassCastException: org.apache.commons.httpclient.methods.GetMethod cannot be cast to org.apache.commons.httpclient.methods.EntityEnclosingMethod
[testng]    at org.jboss.resteasy.client.core.ClientInvoker.invoke(ClientInvoker.java:104)
[testng]    at org.jboss.resteasy.client.core.ClientProxy.invoke(ClientProxy.java:59)
[testng]    at $Proxy138.getMatchingMessages(Unknown Source)

and so on. A variation of this method allows for a date range but, obviously, doesn't work in this form either:

@GET
@Produces("application/xml")
@Consumes("application/xml")
@Path("/matching")
public MessageList getMatchingMessages(@QueryParam("startDate") Date start,
        @QueryParam("endDate") Date end, Message msg);

When I got to thinking about it, passing a Message to a GET method might violate the spirit of REST. Certainly, removing the Consumes annotation from the method allows the client to run without these errors. But it begs the question, what is the right way to write a query method that takes non-URL-based, XML input and produces XML output? Or that takes both XML and url-based parameters and produces XML output?

Answer 1

Do you think you may want to cache the results? If the answer is no, then you can simply use POST instead.

POST /QueryEngine
Content-Type: application/xml

=>
200 OK
Content-Type: application/xml

If the answer is maybe you might want to cache the results then you could do:

POST /QueryGenerator
Content-Type: application/xml

=>
303 See Other
Location: /GeneratedQuery/2323

GET /GeneratedQuery/2323

Having said all of this, are you sure you can't just use query parameters instead of passing XML?

Answer 2

I can't help with the coding side of your question, but if you're passing in a non-URL input, then the POST method would be more appropriate than GET. You are in effect creating a new resource: a list of messages that match the example.