Friday Links

In lieu of a real blog post, here are a few links I've found interesting this past week:

Sitepoint's Josh Catone reviews Evri.

I found two well-written overviews of consistent hashing, one by Tom White and another by Tom Kleinpeter. If your name is Tom and you haven't blogged about consistent hashing, please get on it.

I enjoyed reading Alex's brant (a blog post in the key of rant) A Philosophy of Testing.

On versioning RESTful web services

We did some work refactoring one of our RESTful web services to support versioning of the resources. I came across a post, Versioning REST Web Services by Peter Williams that describes a way to use Accept headers and content negotiation as a way of versioning RESTful services. Basically the client would send "Accept: application/your-app.v1+xml" and the server would then send a response with "Content-Type: application/your-app.v1+xml". Then if you want to make an incompatible change to a resource, the server can respond appropriately based on the Accept header sent by the client. Moreover, a client can declare that it supports multiple versions with associated preference so that a new client could negotiate with an old server, for example. Initially I was really taken with the idea.

In the end, we opted for putting a version tag in the resource URI itself (e.g. /v1/my-app/...). One downside of the Accept/Content-Type approach is that you lose the ability to easily use a web browser to inspect your service since most browsers will not display arbitrary MIME types and prompt you to download instead. There may be some workarounds for this, but the value of being able to quickly inspect services using a browser cannot be discounted -- it is one piece of the leverage one achieves in building services as XML/JSON over HTTP. Another issue surrounds what should happen when the client doesn't send an Accept header at all. If new versions of the web service shouldn't break any existing clients, then the only thing to do for a missing Accept header is either: (i) return an error and force an Accept header to be provided, or (ii) treat the request as if the version requested is the first publicly available version. The second option has the unfortunate effect of making an old version look like the default. The first option is reasonable, but may make the service harder to use since this is not at present a common approach. So the conclusion we arrived at was that placing the version in the resource itself, while someone of an eye-sore, was best since it made the version obviously a required part of the request.

Technorati Tags: ,

archived on 2008-10-03 in

blog comments powered by Disqus