url - Rest URL 标准 - 多路径参数

Question

我们正在构建一个宁静的服务来提供员工数据。

我们有一个 api，它将返回属于客户特定部门的员工列表。

这个 api 有 2 个参数——clientId 和 departmentId

根据标准，以下哪一个是为这个 api 构建一个安静的 url 的正确方法？

1) /client/{clientId}/department/{departmentId}/employees

2) /client/{clientId}/employees?departmentId={departmentId}

一个restful url可以有多个路径参数吗？如果上述问题是/否 - 为什么会这样？

score 8 · Accepted Answer

在 RESTful API 中，路径参数用于标识资源（客户端、订单、博客文章等）。该资源通常是某些数据库中的记录。一些数据库表具有复合键，例如，如果您有一个系统存储有关多个不同客户的员工的数据，那么您的数据库中可能会有条目，例如

name | client_id | department_id
John |    1      |      1
Jane |    2      |      1

两个客户都有一个 id 的部门1。

在这种情况下，如果目的是为给定客户识别给定部门中所有员工列表的资源，那么使用多个路径参数是有意义的。

 /client/{clientId}/department/{departmentId}/employees

但是，如果这更像是一个搜索 API，那么拥有

employees?age={age}&height={height}

score 0 · Accepted Answer

IMO，看起来都不错。如果您希望能够列出所有员工，无论是哪个部门（必要时按部门过滤），请使用第二个。

第一个会使这个用例变得更复杂一些。除非您仍然提供一种让所有员工使用另一个 URI 的方法（但我不建议这样做，因为能够从不同的 URI 中找到相同的信息会使 API 难以理解）。

2 回答 2