RESTful API体系结构约定：如何传递参数

Question

I have some questions about the best way I should allow parameters to be passed to a RESTful API that I program.

Eg I want to retrieve information about a user: API call with method GET would be: /api/users/
Should the id be passed in the url /api/users/5 or as actual GET data /api/users/?id=5

From what I've read and concluded myself I would tend to go for option one (pass the parameter in the url) as it seems more intuitive and very clean.

That option however would be difficult for more elaborate queries. Example: get user by age or last login date or even nested queries (get all posts from user 5). For these use cases it would be much more convient to pass data as request parameters since those would contain key value pairs that can be easily identified ( /api/users/?age=20 )

I'd be interested in your opinion:
Which is the better way to go here and why?
If you prefer option 2: How should the parameters be structured ideally?

Answer 1

Both are applicable

GET /api/users/5 returns the user with ID 5. GET /api/users/?age=20 returns the group of users whose age is 20. GET /api/posts/?user_id=5 returns the group of posts by user 5.

Typically ID is a special case, in that it identifies the resource. You wouldn't search for users by an ID - you just get the one you want.

Answer 2

Keep in mind that for REST, the whole URI, including the query string, is an atomic identifier to the resource. There's no better or worse, as long as the URI always identifies the same resource and is being provided by the service, not constructed by the client.

In that sense, /api/users/5 isn't any more or less RESTful than /api/users?id=5 , but they refer to different things. When you consider the URI semantics, using the parameters for querying collections of resources, /api/users/5 identifies a single user resource, while /api/users?id=5 identifies a collection of users, filtered by id, with a single element result.