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

Question

这里的许多开发人员正在进行友好的(一些人会说是宗教的)讨论，讨论从RESTful API获得请求是否应该返回所请求资源的ID。让我们假设以下GET请求：

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

目前返回的内容如下：

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

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

在这个问题上，基本上有四个阵营在斗争。

夏令营#1:当调用者发出GET请求时，他们已经知道ID了。因此，结果集应该而不是包含ID。如果调用方需要这些数据来进行UI编辑，那么调用方需要传递ID 23，可能会手动将成员{"id"：23}添加到JSON中。

第一营的人员还认为，结果集中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与讨论无关。一号营地在摇摇欲坠的地面上。

你提出的关于集合的观点是非常相关的。对检索-1操作使用一种表示，为检索-N操作使用另一种表示是否合理？我不这么认为。

然而，， --您所面临的问题更普遍--在传递给客户的表示中应该包含哪些数据，以及在什么情况下？在某些情况下，调用者根本不关心属性的一个重要子集。特别是在检索大量对象的场景中--与基本通信成本相比，传输数据的成本更大--您希望优化所运回的对象。

所有足够成熟的REST协议都能够形成返回的数据。

例如，请参见

• Facebook，http://developers.facebook.com/docs/reference/api/
• StackExchange APIv2.0--有一个“过滤器”对象，您可以传递它来精确地构造返回的内容。
• CouchDb API -对每个视图都有一个映射函数，它决定返回哪些数据。它还具有一个总括查询参数include_docs，它指示服务器包含完整的对象或仅包含元数据。(在某些情况下，您可能只需要数据的计数，而不是实际的数据。)

Facebook允许您显式地指定所需的字段。

​

​

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

您可以在https://api.stackexchange.com/docs/answers上看到这一点。

...and特别看到了过滤器规范对话框。

​

​

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

Answer 2

老问题，但既然我来这里寻找什么，这里又有另一种意见：

首先，我认为URL应该是：

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

不

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

"GET“位于HTTP方法上，而不是URL上。它只是命名，但有助于使事情更清楚，IMHO。

如果您考虑到这一点，则需要在同一个URL中使用PUT进行资源修改

放置http://my.api.com/rest/Users/23

在这种情况下，客户端需要跟踪URL，而不是ID。资源是否返回ID字段并不重要。这是由客户保存地图，从哪里获得。

如果尝试使用不同的URL，例如"http://my.api.com/rest/Users/24"，会出现以下几种情况：

1) http://my.api.com/rest/Users/24已经存在于服务器上，服务器接受资源作为更新

2)服务器上不存在http://my.api.com/rest/Users/24，并且：

( a)服务器接受用户向不存在的资源(不推荐)提供ID ( 24 ))服务器接受PUT作为POST

在a+ b中，服务器将创建一个新资源。

所以：

1)取决于您对客户端的信任程度，您可能应该在服务器上创建一个“签入/签出”控件，以避免用另一个资源覆盖一个资源(这是RESTful吗？)

2)您不应该接受创建ID的客户端(可以发布http://my.api.com/rest/Users/，而不是http://my.api.com/rest/Users/24 )，也不应该接受不存在资源的PUT。

编辑

因此，我相信资源是通过它的URL而不是ID来标识的，或者，换句话说，资源ID是http://my.api.com/rest/Users/23，而不是23。

合乎道理?