Have an interesting HTTP API question that I'd like some opinions on. My API allows people to rate things on a 1-10 scale. I have a GET /ratings endpoint that lists a user's ratings. We also want a way to show the user's average rating per day. So my question - should the summary be the same url, like /ratings?data=summary, or should it be its own url like /ratingsummaries or /ratings/summary?
As is often the case, I don't think there is a right answer. Is the summary just another view of ratings, in which case it would be the ratings resource and should be part of /ratings? Or, is a summary of ratings its own resource, in which case it deserves its own url like /ratingsummaries? /ratings/summary looks nice too but it isn't really a sub-resource of ratings.
Looking forward to your feedback. Thanks all!
Answer
My opinion is to have it like /ratings/ when ever your are getting back a list of ratings. The search parameters are usually given as @QueryParam. Eg ratings?offset=20&records=50&startDate=xx&endDate=yy
/ratings/{id}/ for one particular rating identified by the id.
/ratings/{id}/votes for getting for votes on the rating.
Rating summary is different entity from rating so it is a candidate for separte url
/ratingsummary?startDate=x&endDate=y
or your path can start with /ratingsummary; it can be like/ratingsummary/ratings?offset=20&records=50&startDate=xx&endDate=yy
In this case you have the rating summary, then you can drill down to the list of ratings that contributed to the summary, then to one particilar rating, etc..
It is ideal to follow a pattern like /entities/{idOfOneEntiity}/{attributeOfEntitiy} etc.