Hacker News Reader

Comment by kailuowang | Hacker News Reader

RESTful design is still one of the tricky problems I meet on a daily basis. For example, I have blog application in which each blog entry can have multiple versions in its revision history. What should the restful api look like to provide the ability to revert to a certain version?

View on HN

Off the top of my head—have a BlogPost and a BlogPostVersion resource. BlogPostVersion has all the content, and BlogPost simply has a canonical URL and a link to a BlogPostVersion.

You could then PATCH the BlogPost with the link to whatever BlogPostVersion you want to update to.

Curious to see what others would recommend.

Thanks for the reply but maybe I didn't make our requirements clear. The history should be kept intact after the revert - a new version should be created that duplicates the reverted version and become the current version. Thoughts?

Indeed. Creating a new version of your post should be a POST to /posts/X/versions. This would create something like /posts/X/versions/U-U-I-D.

Since REST is all about mapping to the underlying semantics of HTTP you'd then want to make /posts/X redirect to /posts/X/versions/U-U-I-D

Since there's nothing wrong with updating your resource under the hood (think of e.g. http://www.weather.com/weather/right-now/) posts/X would simply always redirect to the latest version.

If you don't always use the latest version by definition, then you'd probably do a PATCH with the new version id to /posts/X, or a PATCH with 'active: true' to /posts/X/version/O-L-D.

If I understand your solution correctly, does it mean that it's now the client's obligation to get the content from the revert-to version and create a new version and POST it to /posts/X/versions? That should work, but what if I don't wanna give the client the ability to create version arbitrarily (only allowed to revert to a pre-existing version)?

My first solution was assuming you could not revert. If you want to allow revert then the client would first call /posts/X/versions, get a list of all versions and then either do

    PATCH /posts/X
    { "version": "older-revision" }

    PATCH /posts/X/versions/older-revision
    { "active": true }

Access control is completely orthogonal to this; so for your sample case you would just return a 403 for any other calls (like e.g. POSTs to /posts/X/versions)

Um, how about POST /blog/id/ and in the request body revert=version#

Seriously REST isn't a mystery. I think the problem is few understand what it is. Here is my 30-second version:

1. Identification of resources and manipulation through representations. This means a network resource should have a URL that is the same no matter what you are doing to it - getting changing, removing, modifying or any custom manipulation. For the Web, use HTTP verbs and request body data to define the actions.

2. Self-descriptive error messages. Don't return 200 OK for everything. Use status codes and verbose response bodies to describe what happened.

3. Hypermedia as the engine of application state. Expose ALL functionality in HTML using hyperlinks and forms.

I am not sure how RESTful that looks to me. I would like to route to the action from the url rather than having to read what's in the body. In your solution, I would need that body parser to differentiate this revert action from an update action.

Irrespective of what is good or bad design, defining an action in the URL goes against the most critical REST principles. Design it whatever way you like, but if you do this, it is not RESTful and you should not refer to it as such.

I think what you have said is correct of how, but not why.

However I think what this whole discussing is missing is the properties that you derive by adhering to a REST design.

I think there should be some tests of a design to see if you are actually getting the benefits of REST.

For example in a REST design you can re-arrange the internal URL's in a server and the site is still usable to clients because they are following links from the root.

Why do we want this ability to rearrange URLs?

The concept of putting URLs in the document is not just so that you can re-arrange them, it's so that you can use HATEOAS.

Example: think of posts here on HN. One thing a specific media format would include is a "reply" link, but on hellbanned posts that link would absent, so that state would be inaccessible to clients.

Or say you've used comments on your blog, so each post has a link to the list of comments about it. Now you switch to Disqus, and so you could change the URL to point to their comments pages instead, and a decent client would use it transparently (assuming good media types).

All of this is taken for granted and used a lot on the real RESTful space: the HTML Web.

RESTful interfaces use HTTP verbs (actions), and the urls contain nouns (things)

All blogs and howtos only describe the change of API Access with new versions, but not how to handle different backend data versions.

One way is to use the newest version in Client and the Server has to convert old Data to new Data, then deliver to Client. But sometimes it not so easy, depend on complexity of your data.

Other way: convert all Data to new Version and change Data-Access in the old Api Version (but here is the Problem with: never change a running system, things that work before could go wrong). And if you have a huge site with many users, it is not possibly to interrupt the service.

To maintain many versions is for a short period ok, but for longer usage not practicable.

Did somebody have experience with that ?

Reply on news.ycombinator.com