json - RESTful GET 响应是否应该返回资源的 ID？

Question

这里的一些开发人员正在就 GET 请求 来自 RESTful API 应返回所请求资源的 ID。让我们假设以下 GET 请求:

http://my.api.com/rest/users/23

这当前返回:

{"name": "Jim", "age": 40, "favoriteColor": "blue"}

请注意，结果集中缺少“id”。

基本上有 4 个阵营在与这个问题作斗争。

营地#1:当调用者发出 GET 请求时，他们已经知道 ID。因此，结果集应为 不是 包括身份证。如果调用者需要此数据来启用 UI 编辑，则调用者需要通过 ID 23，也许手动将成员 {"id": 23} 添加到 JSON。
Camp #1 中的人们还争辩说，结果集中存在 ID 表明该值可以修改，当然不能。

营地#2:如果没有 ID，JSON 结果集就不能原生地用于 UI 表单中的编辑/更新操作。相反，AJAX 回调机制需要负责传递 ID 字段并将这些字段手动添加到结果集中。这似乎很笨拙且容易出错。 UI 人员正在争论结果集“感觉”就像它缺少应该存在的数据，即 ID。

营地#3:这些人关心的是一致性。如果我们曾经有一个 API 返回的用户对象集合，这些对象必须包含 ID。因此，为了保持一致性，GET 的单例版本也应该包含 ID。

营地#4:这些人建议用户的 GET 请求可以以 HyperMedia 或 SelfLinks 的形式返回包含 ID 的元数据。

这不是一个深奥的“谁是对的？”论据，要么。我们采用的方法将决定我们 API 的形状，并影响几个开发人员在新几周内的工作量。

Answer 1

这是一个见仁见智的问题，这不是 Stackoverflow 喜欢看到的那种问题。无论如何，我会提供我的。

您正在返回对象或资源状态的表示。 ID 是该表示的一部分，因此应该包含在 JSON 数据包中。它是资源的属性。调用者是否知道 ID 与讨论的关系并不特别密切。 CAMP #1 处于摇摇欲坠的状态。

你提出的关于收藏的观点非常相关。对retrieve-1 操作使用一种表示，对retrieve-N 操作使用另一种表示是否有意义？我想不是。

但是，您面临的问题更为笼统——传输给客户的陈述中应包含哪些数据，以及在什么情况下？在某些情况下，调用者根本不关心属性的重要子集。尤其是在检索到大量对象的情况下——与基本通信成本相比，传输数据的成本更大——您希望优化返回的内容。

所有足够成熟的 REST 协议(protocol)都有能力塑造返回的数据。

例如，请参阅

Facebook 图形 API，http://developers.facebook.com/docs/reference/api/

StackExchange API v2.0 - 您可以传递一个“过滤器”对象来精确地塑造返回的内容。

CouchDb API - 每个 View 都有一个 map 函数，它决定返回什么数据。它还有一个总括查询参数 include_docs ，它指示服务器包含完整对象或仅包含元数据。 (在某些情况下，您可能只需要数据计数，而不需要实际数据。)

Facebook 允许您明确指定所需的字段。



stackexchange API 很有趣。他们定义了一种全新类型的对象来支持整形。您可以使用 API 定义“过滤器”并将其保存在服务器端。然后在您的查询中传递一个带有过滤器 ID 的过滤器参数，返回的对象表示包括过滤器中指定的所有属性。如果没有过滤器，您将获得“默认”字段子集。要获得“所有字段”，您需要定义一个包罗万象的过滤器。

你可以在 https://api.stackexchange.com/docs/answers 上看到这个。

...并具体查看过滤器规范对话框。



做事没有单一的正确方法。您需要平衡您支持的“塑造”功能的复杂性与开发成本以及将使用 API 的应用程序的需求。