How would you design a RESTful voting system?

Question

In my continuing quest to try and wrap my mind around RESTful-ness, I've come to another place where I'm not sure how to proceed. I set up a thought expiriment for myself where I'd design a simple voting system for a resource, much like how SO allows voting on questions. So, say my resource is an image, and I can get an image by an ID, like so:

http://www.mysite.com/images/123123

And in this example, that returns say, a JSON representation of an image, like so:

{
"URL":"http://www.mysite.com/images/123123.jpg",
"Rep":"100"
}

How would I design a way to "vote" on that image? I'd like two operations; up-vote and down-vote. The client shouldn't know how much weight each carries, because I'd like to have the award for an up-vote/down-vote be decided at the server level so I can change it anytime I like.

My first idea was to have something like this:

http://www.mysite.com/vote/images?image=123123

To that URL, one could POST something like the following:

{
"Vote":"UpVote"
}

But I'm wary of that - to me that says RPC in disguise. Would that be a poor way to design this? If so, what other designs could I try?

Answer 1

It would seem silly to me to POST a simple response like that wrapped in JSON

Why not something simple like this, you could do it in an AJAX call to make it uber nice..

A GET request formatted as follows

http://www.mysite.com/vote.php?image=123&vote=up

or POST (this example using jQuery)

$.post("http://www.mysite.com/vote.php", {image:"123", vote:"up"});

(Assuming PHP, but whatever applies)

Answer 2

If you're working with Rails, I'd go for this GET-URLs:

http://www.mysite.com/images/123123/up_vote

and

http://www.mysite.com/images/123123/down_vote

1. Define the actions "up_vote" and "down_vote" in your Images controller and have it increase or decrease the vote value of your image-model-object.

2. Set the following route in config/routes.rb:

map.resources :images, :member => { :up_vote => :get, :down_vote => :get }

...and you're done (more or less ;-)).

Answer 3

REST APIs are supposed to represent nouns so I think you've the first part correct: a single image is represented by a single URL (e.g. http://www.mysite.com/images/123123). I'm not sure tacking on /up_vote and /down_vote is the way to go though.

http://www.mysite.com/images/123123 is the object and you want to modify that, not some other URL (unless you were doing http://www.mysite.com/votes/images/123123). I think you should just POST to http://www.mysite.com/images/123123. This makes GET requests inherently non-destructive since it just retrieves the image, preserves a RESTful design, and keeps your URLs clean.

Answer 4

To be restful you should return something like this

{
"URL":"http://www.mysite.com/images/123123.jpg",
"Rep":"100"
"UpVoteLink":"http://blah, blah, blah",
"DownVoteLink":"http://blah, blah, something else blah",
}

As far as REST is concerned it doesn't matter what the format of the links are. As long as your client knows that it is supposed to do POST to the "UpVoteLink" or "DownVoteLink" it couldn't care less what the format of the URL is.

Also, if you decide in two weeks that you don't like the URLs you picked, you can change them and no-one will care!

Ok, ok, if you really want a suggestion for an url design, how about

POST http://www.mysite.com/UpVotes?url=http://www.mysite.com/images/1234.jpg

POST http://www.mysite.com/DownVotes?url=http://www.mysite.com/images/1234.jpg

What is cool about this design is that you could vote on images that are not even on your site!

Answer 5

In terms of resources, an image is a thing that has a URI (that is what makes it a resource). Further than that, it has a bunch of properties (size, EXIF data, etc).

When you think of the votes for an image, question if the votes are a resource in themselves.

Chances are, doing a GET on /images/23/votes would return a summary or the list of all votes that the UI would use to display next to the image. Whenever you want to change those votes, the resource you're changing is the votes.

To be restful, the client needs to only understand the media type you've designed, not the URIs or the process to follow to vote.

In your example, you'd define a new format used everywhere on your site. To reformulate yoru example, a GET /images/23/votes would return (in xml but you can reformulate it in json):

<votes>
 <link href="/images/23" rel="subject" />
 <form action="/images/23/votes" mediatype="application/json">
   <submit name="Vote" value="Up">Vote up</submit>
   <submit name="Vote" value="Down">Vote down</submit>
 </form>
</votes>

The idea behind this format is that you have a universal way to define how the client sends the data to the server and build the document. All the previous examles that have been shown correctly make the URI dependent on the server. I propose that what you send to the server should be defined in forms that the server sent.

So spend more time defining how yoru json client is going to understand how to build json objects for submission based on a general form language, and you'll find that once this is done, you have very low coupling between cient and server, and the server has the flexibility to change all the specifics without breaking your clients.