java - 为什么在更新资源时在 URI 中有一个 id 参数？

Question

我正在创建一个 API，我想知道为什么在 PUT 的 URI 中有一个 id 参数很常见？

比如PUT /cars/5 为什么没有PUT /cars？请求实体包含一个 id 字段还不够吗？我可以从该实体获取 id，还是这样做有一些缺点，这样做是否被认为不好？

score 4 · Accepted Answer

因为如果您要向发送PUT请求/cars，从语义上讲，这意味着您正在尝试修改有关汽车集的属性，而不是修改单个汽车的属性。RESTful API 中的 URI 应指示操作所针对的确切资源，因此如果您正在修改资源，您的 URI 应准确指示该资源。

此外，来自RFC 2616：

PUT 请求中的 URI 标识了请求中包含的实体——用户代理知道 URI 的意图，服务器不得尝试将请求应用于其他资源。

因此规范表明，如果客户端知道资源的唯一 ID，则应将其包含在 URI 中。

score 2 · Accepted Answer

这来自休息“意识形态”。

这个想法是一个 url 唯一地代表一个实体 - 所以你必须将你正在创建/编辑的实体放到该实体的 url 中。

引用维基百科页面：

资源识别

在请求中标识单个资源，例如在基于 Web 的 REST 系统中使用 URI。资源本身在概念上与返回给客户端的表示是分开的。

score 2 · Accepted Answer

PUT旨在更新一个精确的实体。

仅使用/cars，您就不会专注于特定实体。

与您所写的相反，您的完整实体不是在基本字符串 (URI) 中传递的。

除非您的目标方法专注于硬编码car id......但我不这么认为......

score 2 · Accepted Answer

它归结为API接口。API 设计有多种方法。而且，就像您建议的那样，您可以将 id 排除在请求之外。但是，由于许多 API 设计都是按照您描述的方式构建的，例如 PUT /cars/5，因此它被认为是一种很好的做法。

基本上，您有 8 种方式与您的 API 进行交互。GET、POST、PUT、DELETE 和一个可选的 HEAD。（如果你算头，总数将是 9 或 10，具体取决于交互）。

因此，要清除它，您有两种 GET 方式。GET /cars 将检索所有汽车，GET /cars/5 将检索任何 ID 为 5 的汽车。因此，您有两种使用 GET 的方法。POST、PUT 和 DELETE 也是如此。4*2 = 8 对吗？

现在，有人会说 PUT /cars 会模棱两可，但是如果没有额外的 ID 字段，您完全可以这样做，因为正如您所提到的，您已经在请求中传递了 ID 字段。

Apigee 的人研究 API 设计已经有一段时间了。我建议观看他们的一些视频，以更好地理解 API 设计的含义以及为什么某些论点有效，而另一些则无效。

4 回答 4