13

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.)

sfussenegger
  • 35,575
  • 15
  • 95
  • 119
  • why do a redirect, why not just return the current version contents that would be the "least astonishing" thing to do –  Apr 02 '10 at 16:40
  • versions don't change while the article itself does (new versions, reverts, ...). Therefore, requesting `/article/4711` could be understood as "What's the latest version of 4711?", "It's version 7", "Cool, I still have that one" ... damn, I'm starting to talk with my API - ready for weekend :) – sfussenegger Apr 02 '10 at 16:50
  • Where can the noobs learn about REST? – maček Apr 02 '10 at 18:15
  • @smotchkkiss I'd suggest http://oreilly.com/catalog/9780596529260 – rytis Apr 03 '10 at 09:18
  • 1
    "/article/4711/version/7" doesn't feel like REST. Is "version" really a subresource of article? Don't you think "/article/4711?version=7", "/article/4711?version=latest" and "/article/4711/comment/2" sound better? – Brian Clozel Apr 08 '10 at 13:18
  • @Brian Not sure, do you? ;) Anyway, in the future, a version might get subresources itself (e.g. `/article/4711/version/7/comments` or `/article/4711/version/7/votes`) hence I'll stick with the current form. One might certainly argue what's better suited though if this wouldn't be the case. Nevertheless, thanks a lot for your thoughts. – sfussenegger Apr 08 '10 at 14:07

5 Answers5

11

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.

rytis
  • 2,649
  • 22
  • 27
  • 1) "/latest" in deed sounds nice. 2) I thought about using `/version` for a list of versions (much like a directory index of contained files). 3) why wouldn't you redirect from `/latest` to `/version/7`. Doesn't it make much more sense if both are the exact same thing? Maybe I'm wondering as I have slight SEO background that makes me shy away from "duplicate content" ;) – sfussenegger Apr 02 '10 at 17:00
  • i'm generally against redirects in APIs and judging by your comment in another answer "I'm not to much concerned about users as the API is XML/JSON only" these pages/URLs aren't for humans... :) In APIs generally it's better to avoid complexities such as redirects as some clients may not be that sophisticated/flexible to handle those. If you're still concerned about SEO/google thing, just add the latest/ URL into robots.txt and tell google to ignore it. – rytis Apr 02 '10 at 17:10
  • 1
    Http redirects are how you redirect to latest versions without breaking caching. Most clients implement redirects transparently, and doing it manually is trivial, so wouldnt' recommend against it. It's a great way to provide Hyperlink support to a ReST API. – SerialSeb Apr 08 '10 at 13:34
2

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.

rjh
  • 49,276
  • 4
  • 56
  • 63
  • I'm not to much concerned about users as the API is XML/JSON only - I know it was only an analogy though ;) I'm not sure if I should consider clients behaving this way. Clients "bookmarking" the location of a temporary redirect are certainly not doing what they are supposed to do. – sfussenegger Apr 02 '10 at 16:46
  • So what's the behavior of an XHTTP client in a redirect like this? I feel a little ignorant even asking this question. I assume the browser is smart enough to transparently do the redirect, but I know IE has surprised me with less desirable behavior than this. – cgp Apr 02 '10 at 16:50
  • @altCognito that's what I was wondering too (it's "harder' to implement" with dump clients). Does somebody have any experience with this? – sfussenegger Apr 02 '10 at 16:55
2

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

Community
  • 1
  • 1
Jan Algermissen
  • 4,930
  • 4
  • 26
  • 39
2

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"/>

...

Chris McCauley
  • 25,824
  • 8
  • 48
  • 65
1

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.

Brian R. Bondy
  • 339,232
  • 124
  • 596
  • 636
  • `/current` sounds like a good idea. I though about using `/article/4711/version` to get a list of all versions (much like a directory index). Does this sound restful to you? – sfussenegger Apr 02 '10 at 16:53