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
Most of what you have looks good. There were just a couple of strange things I saw. When I put my URLs together, I try to follow these four principles.
Peel the onion
If you make the R in REST really be a resource then the resource URL should be able to be peeled back and still be meaningful. If it doesn’t make sense you should rethink how to organize the resource. So in the case below, each makes sense. I am either looking at a specific item, or a collection of items.
The following seems funny to me because
flagisn’t a resource, it’s a property of themovie.Define the View
The last peice of the URL describes how to show the resource. The URL
/movies/horror/tells me I will have a collection of movies refined by horror. But there might be different ways I want to display that collection.The simple view might just be the title and an image. The expanded view would give a lot more information like description, synopsis, and ratings.
Helpers
After the resource has been limited and the proper view figured out, query string parameters are used to help the UI with the little stuff. The most common query string parameters I use are
So I could end up with a URL like
This will give me the list of
movieslimited to horror movies with the default view; starting on page 12 with 50 movies per page where the movies are sorted by name.Actions
The last thing needed are your action on the resource. The action are either collection based or item based.
I hope this helps.