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

Question

这里的一些开发人员正在讨论关于来自RESTful API的GET请求是否应该返回所请求资源的ID的友好(有些人会说是宗教性的).我们假设以下GET请求:

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

目前返回:

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

请注意,结果集中缺少"id".

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

CAMP#1:当呼叫者发出GET请求时,他们已经知道了ID.因此,结果集应该不包括ID.如果调用者需要此数据来启用UI编辑,则调用者需要通过ID 23,可能手动将成员{"id":23}添加到JSON.
Camp#1中的人员也认为结果集中ID的存在表明该值可以被修改,当然它不能.

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

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

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

这不是一个深奥的"谁是对的？" 争论,或者.我们采用的方法将决定API的形状,并影响几个开发人员在新的几周内的工作量.

Answer 1

这是一个意见问题,这不是Stackoverflow喜欢看到的问题.无论如何,我会提供我的.

您将返回对象或资源状态的表示形式.ID是该表示的一部分,因此应该包含在JSON数据包中.它是资源的属性.呼叫者是否知道ID并不特别与讨论密切相关.CAMP#1在摇摇欲坠的地面上.

你提出的关于收藏的观点是非常相关的.为retrieve-1操作使用一个表示是否有意义,以及retrieve-N操作的另一个表示是否有意义？我想不是.

但是,您遇到的问题更为笼统 - 应将哪些数据包含在转移到客户端的表示中,以及在什么情况下？ 在某些情况下,调用者根本不关心属性的重要子集.特别是在检索大量对象的情况下 - 与基本通信成本相比,传输数据的成本更高 - 您希望优化发回的内容.

所有足够成熟的REST协议都能够对返回的数据进行整形.

例如,请参阅

• Facebook Graph API,http://developers.facebook.com/docs/reference/api/
• StackExchange API v2.0 - 你可以传递一个"过滤器"对象来精确地塑造返回的内容.
• CouchDb API - 为每个视图都有一个map函数,用于确定返回的数据.它还有一个毯子查询参数,include_docs它指示服务器包含完整对象或仅包含元数据.(在某些情况下,您可能只需要数据计数,而不是实际数据.)

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

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

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

...并且具体参见过滤器规格对话框.

没有一种正确的做事方式.您需要平衡支持的"整形"功能的复杂性与开发成本以及将使用API​​的应用程序的需求.