Accessing versions/revisions of an object in a RESTful API

Question

While designing a RESTful API we came across the problem of how to access different versions of the "same object". Let us say a page object is identified by a unique key and accessed by GET /api/page/pagekey. It can be updated by sending PUT /api/page/pagekey and an appropriate document in the body.

Now our system keeps track of old versions of the page, that we also want to access via the API. Let us assume that an older version of the document is version 1. There seem to be at least two ways to design the API to access this particular version of the page:

1. GET /api/page/pagekey/1
2. GET /api/page/pagekey?version=1

The first variant renders the particular version as its own resource; the second variant gives the existing resource an optional version context.

• Is variant (1) or (2) a better solution? Or is there an even better way to do it?
• In variant (1) a request for a version number that does not exist e.g. /api/page/pagekey/7 could trigger a HTTP 404 Not Found, which is quit handy. Would this also be a valid status response when considering variant (2), where we only change the context "version" of the existing resource, that would without the version parameter return a HTTP 200 Ok response?

Answer 1

Each resource url should be a permalink to identify that resource.

GET /api/page/{id}/{rev}

That certainly is a permalink to a specific version of the resource. So, that's fine. But note that the permalink does not require the content to be the same over time:

GET /api/page/{id}

That will return the latest revision which is fine and will change contents over time. To expand on that, you can even have temporal resources like this and be RESTful:

GET /api/page/latest 

But, /api/page/{id}?version={rev} will also work and doesn't break any RESTful concepts.

I think the /{id}/{rev} is a bit purer since it specifically identifies that resource in the addressable url and feels a little more correct than putting making it a param. The reason is the params should be modifiers on how to retrieve the contents and not necessarily mutate the distinct resource you're retrieving. In your case, since each version is distinct, it seems more appropriate to distinctly address the resource. But, even that one doesn't break any RESTful url rules or concepts and if you asked 10 folks you might get a different answer :)

Either way, you should likely ensure the temporal resource /api/page/{id} returns the latest revision.