This article caught my eye today: RESTful SOA using XML. Since I’ve been helping a friend to flush out some RESTful service ideas of his own, I wanted to make a comment on this topic…
Generally, the point of using RESTful patterns is to make the information easier to consume. For IBM (and a lot of programmers), "easy to consume" immediately spawns images of XML and automatically generated parsers or XStream or whatever. For me (and a lot of programmers), this same idea spawns ideas of .properties, JSON, flat text, and even HTML…
If you’re writing a web service to expose data to a customer, then shouldn’t you build in support for providing data in their format? After all, "easy to consume" is a valuable trait for data to support. In the interest of supporting the wide variety of people that will eventually be clambering at our door for data, let’s allow them to select their data format. So instead of using these URI’s:
http://luggagetracking.airlinecompany.com/bags/{id} http://luggagetracking.airlinecompany.com/flights/{id} http://luggagetracking.airlinecompany.com/travellers/{id}
RESTful SOA using XML
Add the little bit of extra code to expose these URI’s:
http://luggagetracking.airlinecompany.com/bags/{id}.xml http://luggagetracking.airlinecompany.com/flights/{id}.xml http://luggagetracking.airlinecompany.com/travellers/{id}.xml
http://luggagetracking.airlinecompany.com/bags/{id}.properties http://luggagetracking.airlinecompany.com/flights/{id}.properties http://luggagetracking.airlinecompany.com/travellers/{id}.properties
http://luggagetracking.airlinecompany.com/bags/{id}.html http://luggagetracking.airlinecompany.com/flights/{id}.html http://luggagetracking.airlinecompany.com/travellers/{id}.html
In the article above, we’re already shown how to use regular expressions to parse the interesting bits from the requested url, so switching to a different view based on a file name extension is fairly straight forward. For those of you who are more advanced, this file extension could be cross-referenced with the HTTP Accept header to provide even more complex format selection.
Now I know that some of you are likely responding with doubts. The most likely of these is that exposing the same data in different formats probably isn’t will be worth the investment… and it may not be. It’s unlikely that your web service will greatly benefit from exposing multiple data formats right out of the blocks. However, by building in the assumption that you will do so later, you (a) help guarantee that your view layer will indeed be separated from your model and controllers, and (b) lower the cost of future integration or migration projects.
That brings me to the motivating scenario that I have in my head… For the application my friend is developing, we need to be able to show lay-people what the service “looks like” to remote devices. Showing a machine-readable version of the service’s data to these people is silly. Even if XML was human readable (it’s not), the verbose overhead associated with it makes it relatively unattractive to look at. But HTML… now that (can) look good to people. By using an XML-based template when a .xml URL is requested, and a HTML-based template with a .html URL is requested, we can be friendly to the casual on-looker.
Down the line, we can also use this technique to help integrate test harnesses, debug views, and data documentation. For example, if the data provided by the service seems to be wrong, we take the request (http://foo.com/bar/baz.xml) and swap in .html for .xml and a host of documentation is included along with the data values. Request http://foo.com/bar/baz.debug-html and you get a host of debugging information as well. Whoa, cool.
