Versioned Resources In REST APIs
I like the idea of resources being addressable by a simple URL, but I'm having some difficulty reconciling that with resources that are versioned. Getting at and working with the latest version of a document with REST APIs is all pretty straight forward, but how do you retrieve the document history or a specific version of the document? I'm sure this is something that people have already worked out, but all my searching for discussions of it leads to people talking about versioning the API so that things don't break when you change what operations are available or the data format returned, rather than versioning the resources themselves.
It seems to me that the version information should be available at basically the same place as the main document - it is after all essentially the same document just older. So something like …/resource.html?version=2 makes sense for retrieving a specific version. However, that requires that you know which versions are available - even in a system that doesn't have branching versions may go missing to delete spam or copyright infringement problems. There's also no reason that versions should be simple numbers - they might be 1.1 or a, b, c or just the ETag for that version.
Speaking of ETags, it would be interesting to see how they could be used - there's an If-Match and If-None-Match header for ETags and I've never quite grasped why both exist. It would be nice for one of them to turn out to mean, "I want this exact version" but I doubt it's the case and I really doubt anything out there supports it.
Getting a list of available versions is also an issue - you could consider the list of versions a separate resource (say …/versions/resource.html or …/resource.html/versions) which returns a list of available versions and their meta data but doesn't allow PUT or POST operations. It seems odd though that versions are a separate resource. The other argument is something like …/resource.html?history=all which is okay but needs systems for limiting how much is returned and paging etc.
How are other people handling versioned resources with REST style APIs?
July 27th, 2007 at 1:00 pm
WebDav versioning via rfc3253, perhaps? That’s idle speculation.. I have no experience with such things to know if/when that would be a good idea and when not.
July 27th, 2007 at 1:46 pm
Treat each version as it’s own resource. /document/1 (latest version), /document/1/versions (list of all versions), /document/1/versions/a (a specific version).
July 27th, 2007 at 2:04 pm
DHH,
That seems to match my thinking with …/resource.html/versions (though the brain dump above didn’t wind up saying that). It’s reasonable but still doesn’t quite feel right because the versions are really part of the original resource and this makes it look quite different. It feels more semantically correct to use parameters to request specific aspects of a resource like a specific version or the list of versions. That leads to URLs that don’t really look like REST but I think it matches the semantic ideas better and the normal case is still a nice clean URL. Probably personal taste really.
Dave, WebDAV feels like overkill but is probably the right standards based option.
July 27th, 2007 at 6:39 pm
[...] « Versioned Resources In REST APIs [...]
July 31st, 2007 at 8:07 pm
Adrian,
I would suggest that each version of the doc is a separate resource. It has a relationship to the previous versions (however you encode that, if at all), and may share a fair few attributes with it (such as a similar start of URL). Each version has what you might call a ‘fully qualified’ URL, and you can arrange for a ’short URL’ to get the current one; much like the old Linux distro ‘current’ link idea. The list of versions is a separate resource again.
Cheers,
-Dave.