我应该通过REST API的路径部分或查询部分传递变量吗？(Should I pass variables through the path section or query section of m

我应该通过REST API的路径部分或查询部分传递变量吗？(Should I pass variables through the path section or query section of my REST API?)

我正在构建一个允许用户管理群组的应用。 每个组都包含名称 ， 园区和数据类型 。 它们不属于任何特定的层次结构 - 从语义上讲，校园可以被认为有许多群体，但考虑到层次结构顶层的群体，分布在许多校园中也是很自然的。

name / campus / data_type的组合是唯一的

NAME CAMPUS DATA_TYPE --------------------------------------- LABS WEST IPv4 LABS WEST IPv6 LABS EAST IPv4 USERS NORTH userids USERS WEST userids USERS EAST userids

选项1

很长但相当清晰的URL。

GET /groups/LABS/ (returns LABS groups across all campuses and data_types) GET /groups/LABS/data_type/IPv4 (returns all IPv4 LABS groups across all campuses) GET /groups/LABS/campus/WEST (returns all WEST LABS groups across all data_types) POST /groups/LABS/campus/NORTH/data_type/IPv4 (create a new group) POST /groups/LABS/campus/NORTH/data_type/userids (another new group)

选项2

将组视为层次结构的唯一部分，并将“campus”和“data_type”视为非分层标识符：

GET /groups/LABS GET /groups/LABS?campus=WEST GET /groups/LABS?data_type=IPv4 GET /groups/LABS?campus=WEST&data_type=IPv4 POST /groups/LABS (POST data: {campus: "WEST", data_type: "IPv4}) POST /groups/LABS (POST data: {campus: "WEST", data_type: "IPv4})

Option 1

Long, but fairly clear URLs.

GET /groups/LABS/ (returns LABS groups across all campuses and data_types) GET /groups/LABS/data_type/IPv4 (returns all IPv4 LABS groups across all campuses) GET /groups/LABS/campus/WEST (returns all WEST LABS groups across all data_types) POST /groups/LABS/campus/NORTH/data_type/IPv4 (create a new group) POST /groups/LABS/campus/NORTH/data_type/userids (another new group)

Option 2

Treat the group as the only part of the hierarchy, and treat "campus" and "data_type" as non-hierarchical identifiers:

GET /groups/LABS GET /groups/LABS?campus=WEST GET /groups/LABS?data_type=IPv4 GET /groups/LABS?campus=WEST&data_type=IPv4 POST /groups/LABS (POST data: {campus: "WEST", data_type: "IPv4}) POST /groups/LABS (POST data: {campus: "WEST", data_type: "IPv4})

ADVANTAGE:

it seems to reflect the non-hierarchy of "data_types" and "campus", and makes it easy to specify (say) campus without a data_type (or vice versa).

DISADVANTAGES:

I'm not totally sure this is an appropriate use of query parameters. Furthermore it does not provide a very pretty "permalink" to any unique combination of group/campus/data_type.

I'm leaning towards option 2. Is that the best way to represent this data? Or am I thinking about it wrong?

最满意答案

我建议改为支持两个端点。 从您的描述中可以清楚地看出，组不是由名称唯一定义的，但您的URI结构暗示它是。 相反，使用合成ID来唯一标识组。

GET /groups ?name={} ?campus={} ?data_type={} <- some collection of all groups that match whichever criteria are specified POST /groups -> { "name": "LABS", "campus": "WEST", "data_type": "IPv4" } GET /groups/{id} <- { "name": "LABS", "campus": "WEST", "data_type": "IPv4" }

这种方法在将来决定添加新属性或希望跨所有组搜索data_type时为您提供更大的灵活性。

您可以在服务器（meh）的响应中包含唯一ID，也可以包含超媒体链接以提供有趣的关系，例如所有其他具有相同名称的组，或者在同一个园区中。

I would suggest instead supporting two endpoints. It's clear from your description that a group is not uniquely defined by a name, but your URI structure implies that it is. Instead, use a synthetic id to uniquely identify a group.

GET /groups ?name={} ?campus={} ?data_type={} <- some collection of all groups that match whichever criteria are specified POST /groups -> { "name": "LABS", "campus": "WEST", "data_type": "IPv4" } GET /groups/{id} <- { "name": "LABS", "campus": "WEST", "data_type": "IPv4" }

This approach gives you more flexibility for in the future when they decide to add a new property, or want to search by data_type across all groups.

You can either include unique ids in responses from the server (meh) or include hypermedia links to give you interesting relationships, such as all other groups with the same name, or on the same campus.