RESTful reporting

REST (REpresentational State Transfer) is a method for building web services. It is an alternate to things like SOAP and XML-RPC. REST is put forward as a cleaner method of doing web services, and so far (though I’ve virtually no experience to base it on) I’ve been persuaded by those arguments.

The REST concept is that you have URLs (nouns) and the basic HTTP operations (verbs). Proper REST uses only the core HTTP verbs GET, PUT, DELETE, and POST if at all possible (though opinion on what function POST should serve is divided.)

The HTML based web (without cookies and other such stateful objects) is one example of REST in action. This consists primarily of GET, with CGI parameters and even non-CGI sometimes abused (i.e., non-RESTful) as verbs, and POST primarily used for larger CGI operations – most cacheing schemes will consider a POST has possibly having side effects.

Another canonical example is an online parts database. You might have a /partslist URL that retrieves an XML file wth the URLs of the parts, which might be like /parts/12345.


So there’s the quick tour of REST. Now for the trouble. As I’m presently discovering, even a parts database has it’s complications. The real stickler is reports.

In theory a REST URL is a ‘noun’ – it is a thing, and it is the same thing every time it is fetched. (Unless somebody has PUT a new version) Reports are somewhat more nebulous. The problem is that they don’t have canonical forms (or, at last, enumerating the forms is prohibitive.)

My first experiment was on-time shipping. So, /ontimeship. Now, you might want to only show a certain time period. Certain queries can be handled by, say, /ontimeship/date/2007/02 – a pattern I’ve seen in some blogs. In this each level of the URL provides a new level of grouping. But what if you want the last 30 days? /ontimeship/days/30? What if you want to look at a 30 day window one year ago?

One article suggested using the CGI parameter ?mimeType= in a REST context. So, parameters can modify the data. It is reasonable to use them to modify the results. So, /ontimeship/all?sdate=01/01/2007&edate=02/01/2007. CGI parameters are part of the URL, so caching engine could in principal make use of them.

But now that feeds back in the URL scheme – if parameters can provide different views, why bother with paths like ./date/2007/02? Isn’t that just another filter? In this case it provides grouped results, but why not ‘?group=month’? At some point, /date/2007/02/all provides a list that is just like the basic report, but with the appropriate sdate and edate applied. Great, now we’ve got aliasing.

Of course, you could also invert the whole scheme. How about /date/2007/02/ontimeship? Should it be /ontimeship/customer/123 or /customer/123/ontimeship? What if I want to date filter it too? Secondary grouping? Different sort orders? And of course, to make a simple interface with HTML forms, working with CGI parameters is a heck of a lot easier than the pathing scheme. You’d need some kind of javascript or other dynamic behavior to do URL construction.

Messy, eh?

Posted Tuesday, February 27th, 2007 under Essay.

Comments are closed.