Address an ordered list the RESTful way

Question

I doubt what's the best way to address an ordered list in a RESTful API. Imagine the following example: Let's create a chart list of LPs, where you want to add new LPs, delete those which aren't in the TOP10 yet, and change their positions. How would you implement those methods in a RESTful JSON-API?

I thought of the following way:

• GET / to return the ordered chart list like [{ "name": "1st-place LP", "link": "/uid123" }, { "name": "2nd-place LP", "link": "/uid987" }, ...]
• GET /{uid} to return a LP by its unique ID, returning sth. like {"name": "1st-place LP", "ranking": 1 }
• GET /ranking/{position} to access e.g. the current first-ranked LP, returning a 303 See Other with a Location-header like Location: /uid123
• POST / with request body { "name": "my first LP title" } to create a new LP without specifying its current chart position

Now it's the question how we could change the current chart positions? One could simply PUT /{uid} to update the ranking attribute, but I think a PUT /ranking/{position} would be more natural. On the other hand it doesn't make sense to PUT against an URI which will return a 303 See Other when using GET.

What do you think would be the best way to address such a chart list? I don't like the solution of changing simply the ranking attribute in the LP-datasets as this could end in senseless states like two LPs with the same ranking and so on.

Answer 1

You have two collection resources within your music service. As such, I would design a URI structure like this:

/ => returns links to collections (ergo itself a collection resource)
/releases => returns a list of LPs
/chart => returns the top 10 LPs, or redirects to the current chart URI

You would POST to /releases to add a new LP, and PUT or PATCH to /chart to define a new chart or alter the current chart. You will need to define what representation formats are transfered in each case.

This gives you the flexability to define thinks like /chart/2012-12-25 to show the chart as it stood on christmas day 2012.

I do not suggest using PUT /chart/{position} to insert an LP at a specific position and shuffle everything else down. Intermediarys would not know that a PUT to that URI causes other resources to change their URIs. This is bad for caching.

Also, as a user, I would hope you avoid the word "billboard" as the other answer suggests. A billboard conjures in the mind pictures of an advertising hoarding, and not anything to do with ranking charts!

Answer 2

I see two questions. 1. What is the most RESTful (beautiful) way to design the API? 2. How do I make sure that two LPs does not get the same ranking?

1: Your LPs could have several properties that are relative to eachother, e.g. different ranking on different charts. I would say that you want the ranking moved OUT of your LP resource. Keep the ranking on a certain list as a separate resource. Example:

• GET /LPuid only returns properties about the LP, not relative properties, like rankings
• GET /billboard/3 returns the URI to LP that has rankning 3 on the billboard list.
• PUT /billboard takes a document of 100 LP URI's.
• PUT /billboard/3 INSERTS an LP URI at that ranking and moves the other ones down.

2: That has nothing to do with rest and you would have that issue no matter how you design your API. Transactions is one solution.