CODEWITHSUNDEEP
resthttp-caching
sfussenegger
sfussenegger

Reputation: 36105

REST: Should I redirect to the version URL of an entity?

I am currently working on a REST service. This service has an entity which has different versions, similar to Wikipedia articles.

Now I'm wondering what I should return if for

GET /article/4711

Should I use a (temporary) redirect to the current version, e.g.

GET /article/4711/version/7

Or should I return the current version directly? Using redirects would considerably simplify HTTP caching (using Last-Modified) but has the disadvantages a redirect has (extra request, 'harder' to implement). Therefore I'm not sure whether this is good practice though.

Any suggestions, advise, or experiences to share?

(btw: ever tried search for "REST Version"? Everything you get is about the version of the API rather than entities. So please bear with me if this is a duplicate.)

Upvotes: 13

Views: 1165

Answers (5)

Chris McCauley
Chris McCauley

Reputation: 26413

Article versions and hypertext

If you're really concerned about making the interface RESTful then you should consider how to do this in a HATEOS style.

In my opinion that would mean returning enough information that the user is able to navigate through the list of revisions of your entity. If you read this from Roy ...

"The interface doesn’t need to be discovered. It is defined right there in the hypertext. The representation tells the client how to compose all transitions to the next application state"

... you'll get a feel for how your GET /article/4711 should return enough information to

  1. Get the latest version of the article

  2. Get the next/previous versions

You'll know what works best for your model but as a pointer you could consider using tags 

  <link rel="older"
        type="text/html"
        href="http://www.yourdomain.com/article/4711?version=6"/>

...

Upvotes: 2

Jan Algermissen
Jan Algermissen

Reputation: 4978

You might want to look at https://datatracker.ietf.org/doc/html/draft-brown-versioning-link-relations .

Using the CMIS link relations and the HTTP Link header you can make /article/4711 the latest and provide a link to the versions, e.g. Link: </article/4711/versions>;rel=version-history

Upvotes: 2

Brian R. Bondy
Brian R. Bondy

Reputation: 347466

I think it would be more restful to return a list of the revisions for:

GET /article/4711

You could also have:

GET /article/4711/current

Which returns the current version directly.

Upvotes: 1

rytis
rytis

Reputation: 2721

If you treat versions as entities (which by the looks of it you do) this is what I'd suggest:

GET /article/4711

returns a list of all versions (and links to them). Which makes /article/4711 a container entity.

GET /article/4711/latest

returns contents of the latest version. You might want to consider /version/latest to get in-line with the below.

GET /article/4711/version/7

returns the specific version of the article.

Upvotes: 11

rjh
rjh

Reputation: 50324

Depends on your intended behavior for GET /article/4711. If it is intended to always point to the latest version, then it should return the latest version directly. Redirecting to a particular version seems problematic as you are relying on the user/client library to not visit that particular URL in the future. To translate into HTML terms, a user might bookmark the version/7 URL and be surprised that they are now accessing an older version instead of the up to date version they originally typed into the address bar.

Upvotes: 2

Related Questions