5 ms·

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 vers

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?

beaumartinez 13y ago
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.
- kailuowang 13y ago
  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?
- mtrimpe 13y ago
  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/ 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.
  - kailuowang 13y ago
    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)?
    - mtrimpe 13y ago
      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" } or 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)
protonfish 13y ago
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.
- kailuowang 13y ago
  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.
  - protonfish 13y ago
    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.
    - artsrc 13y ago
      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?
      - 13y ago
apidoc 13y ago
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 ?

beaumartinez 13y ago

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.

kailuowang 13y ago
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?
mtrimpe 13y ago
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/ 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.
- kailuowang 13y ago
  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)?
  - mtrimpe 13y ago
    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" } or 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)

protonfish 13y ago

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.

kailuowang 13y ago
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.
- protonfish 13y ago
  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.
  - artsrc 13y ago
    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?
    - 13y ago

apidoc 13y ago

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 ?