StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

POREST URIs and operations on an object that can be commented on, tagged, rated, etc
text
Body
copied!<p>I'm doing research into a web API for my company, and it's starting to look like we might implement a RESTful one. I've read a couple of books about this now (O'Reilly's "RESTful web services" seeming the most useful) and have come up with the following set of URIs and operations for an object that can be commented on, tagged, and rated. </p> <p>It doesn't really matter what the object is, as this scenario applies to many things on the net, but for the sake of argument lets say it's a movie.</p> <p>Some of these seem to fit quite naturally, but others seem a bit forced (rating and tagging particularly) so does anybody have any suggestions about how these could be improved? I'll list them with the URI and then the supported verbs, and what I propose they would do.</p> <pre><code>/movies </code></pre> <p>GET = List movies</p> <pre><code>/movies/5 </code></pre> <p>GET = Get movie 5</p> <pre><code>/movies/5/comments </code></pre> <p>GET = List comments on movie 5</p> <p>POST = Create a new comment on movie 5</p> <pre><code>/movies/5/comments/8 </code></pre> <p>GET = Get comment 8 on movie 5</p> <p>POST = Reply to comment 8 on movie 5</p> <p>PUT = Update comment 8 on movie 5</p> <pre><code>/movies/5/comments/8/flag </code></pre> <p>GET = Check whether the movies is flagged as inappropriate (404 if not)</p> <p>PUT = Flag movie as inappropriate</p> <pre><code>/movies/5/rating </code></pre> <p>GET = Get the rating of the movie</p> <p>POST = Add the user rating of the movie to the overall rating</p> <p><em>Edit: My intention is that the movie object would contain its rating as a property, so I wouldn't really expect the GET method to be used here. The URI really exists so that the rating can be an individual resource that can be updated using the POST verb. I'm not sure if this is the best way of doing it, but I can't think of a better one</em></p> <pre><code>/movies/5/tags/tagname </code></pre> <p>GET = Check whether the movies is tagged with <em>tagname</em> (404 if not; but if it is tagged with the tag name should it return the actual tag resource by redirecting to something like <code>/tags/tagname</code>?)</p> <p>PUT = Add tag <em>tagname</em> to the movie, creating the tag resource <code>/tags/tagname</code> if required</p> <p>DELETE = Remove tag <em>tagname</em> from the movie, deleting the tag resource <code>tags/tagname</code> if nothing is tagged with it after this removal</p> <hr> <p>Note that these wouldn't be the entire URIs, for example the URI to list the movies would support filtering, paging and sorting. For this I was planning on something like:</p> <pre><code>/movies/action;90s/rating,desc/20-40 </code></pre> <p>Where:</p> <p>action;90s is a semi-colon delimited set of filter criteria</p> <p>rating,desc is the sort order and direction</p> <p>20-40 is the range of item indices to get</p> <p>Any comments about this API scheme too?</p> <hr> <p><strong>Edit #1</strong></p> <p>This post is getting quite long now! After reading some of the answers and comments, this is the changes from above I'm planning on making:</p> <p>Tags will be handled as a group rather than individually, so they will be at:</p> <pre><code>/movies/5/tags </code></pre> <p>GET = List tags</p> <p>POST = Union of specified tags and existing tags</p> <p>PUT = Replace any current tags with specified tags</p> <p>DELETE = Delete all tags</p> <p>I'm still really not sure how to handle flagging a comment though. One option is that instead of POSTing to a comment replying to it, a comment object will include its parent so it can be POSTed to the general URI, i.e.</p> <pre><code>/movie/5/comment </code></pre> <p>POST = Create a new comment (which may be a reply to a comment)</p> <p>I could then use the POST to a comment to flag it. But this still doesn't feel quite right.</p> <pre><code>/movie/5/comment/8 </code></pre> <p>POST = Flag comment</p>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload