REST URIs and operations on an object that can be

Question

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.

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.

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.

/movies

GET = List movies

/movies/5

GET = Get movie 5

/movies/5/comments

GET = List comments on movie 5

POST = Create a new comment on movie 5

/movies/5/comments/8

GET = Get comment 8 on movie 5

POST = Reply to comment 8 on movie 5

PUT = Update comment 8 on movie 5

/movies/5/comments/8/flag

GET = Check whether the movies is flagged as inappropriate (404 if not)

PUT = Flag movie as inappropriate

/movies/5/rating

GET = Get the rating of the movie

POST = Add the user rating of the movie to the overall rating

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

/movies/5/tags/tagname

GET = Check whether the movies is tagged with tagname (404 if not; but if it is tagged with the tag name should it return the actual tag resource by redirecting to something like /tags/tagname?)

PUT = Add tag tagname to the movie, creating the tag resource /tags/tagname if required

DELETE = Remove tag tagname from the movie, deleting the tag resource tags/tagname if nothing is tagged with it after this removal

---

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:

/movies/action;90s/rating,desc/20-40

Where:

action;90s is a semi-colon delimited set of filter criteria

rating,desc is the sort order and direction

20-40 is the range of item indices to get

Any comments about this API scheme too?

---

Edit #1

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:

Tags will be handled as a group rather than individually, so they will be at:

/movies/5/tags

GET = List tags

POST = Union of specified tags and existing tags

PUT = Replace any current tags with specified tags

DELETE = Delete all tags

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.

/movie/5/comment

POST = Create a new comment (which may be a reply to a comment)

I could then use the POST to a comment to flag it. But this still doesn't feel quite right.

/movie/5/comment/8

POST = Flag comment

Answer 1

Based on my understanding of ROA (I'm only on chapter five of RESTful Web Services) it looks good to me.

Answer 2

I disagree with the edit. Queries should be defined by querystrings as per Martijn Laarman's post. i.e.:

/movies?genre=action&timeframe=90s&lbound=20&ubound=40&order=desc