RESTful way to handle related resource for both specific instances of a resource and all of that resource

Question

I am designing a RESTful API that has a set up like this:

/users - returns all users

/users/123 - returns user with the id 123

/users/123/comments - returns all comments for user 123

I am looking for the most correct way to return all comments for all users. Comments don't have their own ID or identifier and they don't exists outside of the context of a user, so I don't think that /comments would be ideal. I also don't think that /users/comments would be ideal because then comments are moving up and down the resource. I have also though about using Prefer headers to filter down the data that is being returned from /users to just those comments.

I'm not sure which way, or if another way, is best. The actual resource I am using are not users and comments, but I think it's a reasonable enough example.

Answer 1

It seems to be a popular fallacy that subpaths must indicate context. There's nothing wrong with using /comments to track all comments. It gives you a lot of flexibility later if you decide to allow clients to work with individual comments.

Answer 2

Keep in mind that URIs are identifiers. They don't necessarily have to provide developers with the implementation details of the server-side.

From the API consumer point of view, the hierarchy or the relationship between user and comments should be explicit in the resources representantation, not in the resource identifiers.

If you consider the whole collection of comments to be a resource, then provide the resource with a URI, no matter how the resource is modeled in the server-side.

The URI /comments is perfectly valid. And be quite because the API will continue to be REST.

I will share here some links that might help you to look at the problem from a different point of view.

W3.org

(A bit old, but still valid)

Axiom: Opacity of URIs

The only thing you can use an identifier for is to refer to an object. When you are not dereferencing, you should not look at the contents of the URI string to gain other information.

For the bulk of Web use URIs are passed around without anyone looking at their internal contents, the content of the string itself. This is known as the opacity. Software should be made to treat URIs as generally as possible, to allow the most reuse of existing or future schemes.

This axiom has not changed over the years.

URI's RFC

Consumer point of view

1.2.3. Hierarchical Identifiers

The URI syntax is organized hierarchically, with components listed in order of decreasing significance from left to right. For some URI schemes, the visible hierarchy is limited to the scheme itself: everything after the scheme component delimiter (":") is considered
opaque to URI processing. Other URI schemes make the hierarchy
explicit and visible to generic parsing algorithms.

Developer point of view

1.2. Design Considerations

1.2.1. Transcription

[...]

A URI often has to be remembered by people, and it is easier for people to remember a URI when it consists of meaningful or familiar components.

While the URI is opaque to the consumer, it's not necessarily opaque to the human. So we still can make URIs readable as soon as it doesn't condition the system. Ultimatelly, the requirements has the final say.