REST URIs and operations on an object that can be commented on, tagged, rated, etc

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 \"

Answer 1

Well, the way I see it some of the information you return now as objects could simply be added to the metadata of its parent object.

For instance, rating could be part of the response of /movies/5

<movie>
   <title>..</title>
   ..
   <rating url="movies/ratings/4">4</rating>
   <tags>
      <tag url="movies/tags/creative">creative</tag>
      ...

Removing a tag simply means posting the above response without that tag.

Also queries should go in URL variables, I believe: /movies/?startsWith=Forrest%20G&orderBy=DateAdded

Answer 2

@Nelson LaQuet:

Using the HTTP methods as they are actually defined gives you the safety of knowing that executing a GET on anything on a web site or service won't eat your data or otherwise mangle it. As an example (pointed out in RESTful Web Services) Google's Web Accelerator expects this behaviour -- as stated in the FAQ -- and presumably other services do too.

Also it gets you idempotency for free. That is doing a GET, DELETE, HEAD or PUT on a resource more than once is the same as doing it only once. Thus if your request fails then all you have to do is run it again.

Answer 3

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.

/movies/horror/10/
/movies/horror/
/movies/

The following seems funny to me because flag isn't a resource, it's a property of the movie.

/movies/5/comments/8/flag -> Funny
/movies/5/comments/8/     -> Gives me all properties of comment including flag

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.

/movies/horror/simple
/movies/horror/expanded

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

p => Page
n => number of items to display
sortby => field to sort by
asc => sort ascending

So I could end up with a URL like

/movies/horror/default?p=12&n=50&sortby=name

This will give me the list of movies limited 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.

/movies/horror/
GET -> Get resources as a list
POST -> Create, Update

/movies/horror/10/
GET -> Get resource as item
POST -> Update

I hope this helps.

Answer 4

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

Answer 5

This is an awesome initial draft for a spec of a REST API. The next step would to specify expected return codes (like you did with "404 No Tag Available"), acceptable Content-Types, and available content-types (e.g., HTML, JSON). Doing that should expose any additional chinks you'll need to hammer out.

Answer 6

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