REST API design best practice

Where does this endpoint belong and how should it be:

GET /users/1/comments/

or

GET /comments&userId=1

In UserController where I do

@GetMapping("/user/{userId}/comments/")
    public ResponseEntity<List<Comment>> getAllComments(@PathVariable Long userId) {
        return ResourceUtil.getResponseEntity(Optional.of(userService.getUser(userId).getComments()));
    }

Or it should be in CommentController:

@GetMapping("/comments/")
    public ResponseEntity<List<Comment>> getAllComments(@RequestParam Long userId) {
      User user = userService.getUser(userId);
      List<Comment> comments = commentService.getComments(user);
      return ResourceUtil.getResponseEntity(comments);
    }

?

If I choose to follow this convention:

GET /users/1/comments/ then I end up with only 1 controller - namely UserController for all resources, as all other resources could be seen as a sub-resource to /users. For example:

GET /users/1/articles/
GET /users/1/jobs/
GET /users/1/applications/
GET /users/1/posts/

and so on...

Is it a good idea to map /users/ to different controllers so in this case:

GET /users/1/articles/ -> ArticlesController

GET /users/1/jobs/ -> JobsController

GET /users/1/applications/ -> ApplicationsController

GET /users/1/posts/ -> PostsController

?

Update

I think this is not correct:

GET /users/1/comments/ because for any given user's entitties we will end up prefixing them with the same value /users/1 which is wrong. Authentication and Authorization should happen seemlessly, therefore the Controller should be able to extract user information from request headers / JWT token and they should not be part of the API unless it is an admin endpoint and the admin could look at any user, but this endpoint should be completely separate.

Correct way is
/users/1/comments/

All the resources should be identified by URL path (not the query parameters).
Only data that are not resources identifiers should be query parameters
/users/1/comments?startsWith=mark&page=3

Each of the versions you presented can be "correct"; they mean slightly different things.

In the first case, you are treating comments as a subresource of the user; that is, the comments have no meaningful existence outside it. It is entirely conventional to use this style if you're representing, say, the user's authentication information or preferences. This style is equivalent to using a SQL JOIN, and you would use it where you might use a cascade delete in your database.

In the second case, you're treating comments as a first-class top-level resource that stands alone and merely has a relationship to the user. The query parameter is the HTTP equivalent of a WHERE clause.

Whether to treat comments as a top-level or a subresource is a design decision for you to make. Factors that weigh in favor of a top-level resource include querying by various different relationships all the time (e.g., it's more common to query by ?article= than ?user=!) and whether it makes sense to address a comment by ID without reference to the user who posted it.

REST doesn't care what spellings you use for your identifiers, so long as they conform to the production rules defined by RFC 3986

GET /users/1/comments/
GET /comments&userId=1
GET /79f541f3-e872-47ba-9ef6-63667e148455

Those are all fine.

Part of the point is that the identifiers are just identifiers; as far as general purpose components are concerned, the identifiers are semantically opaque, so you can do what you want with them.

In some cases, you'll want to take advantage of relative references, which allow you to manipulate the path segments (aka the "hierarchical part") of the identifier to easily compute other identifiers.

For example, it may be convenient that

/users/1 == base(/users/1/comments/).resolve(../..)

If you are expecting to use RequestParam mappings, you need to make sure that the those key value pairs appear in the query part of the URI. In other words, both of these spellings are fine (from the perspective of a general purpose client)

GET /comments&userId=1
GET /comments?userId=1

But the second one is going to be a lot easier to work with than the first when you are implementing your routing.

An extra advantage to key/valye pairs is that HTML semantics include form processing rules that understand how to transform a data and metadata from input controls into application/x-www-form-urlencoded key value pairs in the query part of an identifier.

Remember, a REST API is a facade; your implementation pretends to be a dumb web site so that you can take advantage of any and all of the existing general purpose components that understand how we talk to dumb web sites. On a web site, the URI is just an opaque key that we use to pull a document out of a store (in much the same way that we can use a string to extract a value from a java.util.Map<String,Value> ).

I don't have an answer for you, because it really depends on your circumstances.

Consider this: can a comment exist without a user? If the comment is related to a product, who owns the comment, the user or the product? If you don't have an answer to that, you should ask: to which 'class' the comment is more important? If you lose a user, should you lose the comment?

When designing APIs, I always ask these questions. Hope it helps a bit.

By convention, for each resource you need a controller. It is the level 1 of the Richardson Maturity Model.

So the best solution is number 3. But I think userId will be a foreign key in the comment table, so you can use it directly without get the user for the DB.

You can see this article for the Richardson Maturity Model :
Richardson Maturity Model