RESTful ordered list address
I doubt the best way to address an ordered list in a RESTful API. Imagine the following example: let's create a list of LP charts where you want to add new LPs, delete those that are not yet in the TOP10, and change their positions. How do I implement these methods in a RESTful JSON API?
I thought about the following:
- GET / to return an ordered list of charts like
[{ "name": "1st-place LP", "link": "/uid123" }, { "name": "2nd-place LP", "link": "/uid987" }, ...]
- GET / {uid} to return LP by its unique id, returning sth. as
{"name": "1st-place LP", "ranking": 1 }
- GET / rank / {position} to access eg. the current LP with the first rank, returning
303 See Other
with a Location header, for exampleLocation: /uid123
- POST / with request body
{ "name": "my first LP title" }
to create a new LP without specifying its current chart position.
Now the question is, how can we change the current positions in the diagram? You can just PUT / {uid} update the attribute ranking
, but I think PUT / rank / {position} will be more natural. On the other hand, it doesn't make sense to PUT against the URI that will return 303 See Other
when using GET.
What do you think is the best way to refer to such a list of charts? I don't like the decision to change just an attribute ranking
in LP datasets, as this could end up in meaningless states like two LPs with the same rank, etc.
source to share
I see two questions. 1. What's the most RESTful (beautiful) way to develop an API? 2. How can I make sure two LPs don't get the same rating?
1: Your LPs can have several properties that relate to eachother, for example. different ratings on different charts. I would say that you want the rating to move from your LP resource. Keep your rating on a specific list as a separate resource. Example:
- GET / LPuid only returns LP properties, not relative properties like ranking
- GET / billboard / 3 returns the URI for LP, which ranks 3rd in the billboard list.
- PUT / billboard accepts document from 100 LP URIs.
- PUT / billboard / 3 INSERT LP URIs in this rating and moves others.
2: It has nothing to do with rest and you will have this kind of problem no matter how you design your API. Transactions are one solution.
source to share
You have two collection resources in your music service. Thus, I would design the 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 could POST
before /releases
add a new LP and PUT
or PATCH
in /chart
to define a new schedule or change the current schedule. You will need to determine which presentation formats are passed in each case.
This gives you the flexibility to define what it looks like /chart/2012-12-25
to show the graph as it stood on Christmas Day 2012.
I am not suggesting using PUT /chart/{position}
LP to insert at a specific position and shuffle everything else. The intermediaries are unaware that the PUT for this URI causes other resources to change their URIs. This is bad for caching.
Also, as a user, I hope you avoid the word "billboard" as another answer suggests. The billboard conjures up photos of advertising accumulation, and has nothing to do with ranking charts!
source to share