First, an alternative to consider...
After many years of designing and implementing web services (and inheriting some rather sub-par implementations as well), I've reached a conclusion that some others have as well: Avoid nested resource paths.
Matthew Beale's Suggested REST API Practices article explains the reasoning behind this. (Look in the First-class Models section.)
But if you insist...
If you have to (or prefer to) use nested resource paths, I would suggest grouping methods based on what type of resource they return. So /users/:id/games
would be implemented in GamesController
. My reasoning here is that it maintains a more consistent correlation between API classes and DAL classes, which helps avoid guesswork later on, and reduces the number of inter-class dependencies.
I think your querystring suggestion is the cleanest, basically for the same reasons as #1 (it returns a game, so it should be under the /games
resource, and implemented in GamesController
). Something like /games?keyword=hot&limit=1
resembles the pattern of successful, intuitive API approaches I've seen used elsewhere.
Why not both?
Which is to say, yes, there are trade offs to consider, but if the marginal cost of implementing a second option is small, you can offer to your clients the ability to select which representation they prefer, so that they can choose their own trade offs (of course, there's some complexity penalty to be paid by offering a choice, rather than solving "the" problem for the clients).
The major con I see is that you've built an endpoint tightly coupled to this particular view within this particular application.
Not quite the right language, from a REST perspective. It's not the endpoint that is coupled to the application, but the media type of the representation.
Of course, worrying about media types tends to fall by the wayside when we are implementing both the client and the server, and their release cycles are coupled.
The pros of 2. are that we are using nothing but generic resource endpoints, which could be re-used by many different views and applications.
That thought is incomplete - you can not only reuse the endpoints, but you can re-used the representations themselves... ie: caching. If the client can pull the data it needs out of its own cache, then it doesn't need to round trip at all. Failing that, an intermediate cache may already have a copy of the data, shortening the round trip. The "server" that the client is talking to might be a cache farm in front of your app, keeping the workload low while being able to scale out.
In REST, you want to make sure that your designs take advantage of the uniform interface.
So one of the things you should be thinking about is the cache lifetime of your resources; how long are representations valid? Are other views and applications going to be able to take advantage of that?
Should the fact that this API is an internal company API (and almost certain to remain so), rather than a public facing one, influence my decision?
That's likely to put limits on the volume of traffic you'll need to support. Also, if the clients are all going to be centrally located, then round trip time falls away as a concern as well.
Best Answer
If the content is identical, it's unclear what "differences" would be seen in list vs. calendar. If the result is a JSON or XML document, there should be no discernible difference.
if the result is an HTML page, where formatting is part of the results, then the path is the correct thing to do, since the content is different.
You have several choices.
Path changes. "/path/to/resource/view/id/" works well for us. Our views include "html", "xml" and "json".
However, your "list" vs. "calendar" may or may not be the same content, in the a single format, and a different organization. So you have a number of issues tangled up together in your question.
Query String changes. This: "?view=calender" or "?view=list".
Fragment changes. This: "#calendar" or "#list". These can work well in your case, since the two views seem to have different content.