如果一个RESTful GET响应返回资源的ID？ [英] Should a RESTful GET response return a resource's ID?
问题描述
若干这里正处于一个友好的开发者（有人说是宗教）关于是否 GET请求从的RESTful API 应的返回ID讨论所请求的资源的的。让我们假设以下GET请求：
http://my.api.com/rest/users/23
这目前返回：
{名：吉姆，年龄：40，favoriteColor：蓝}
请注意，ID是从结果集中遗漏。
基本上有4营这个问题作战。
CAMP＃1：：当呼叫者可以GET请求，他们已经知道的ID。因此，结果集应的不可以包括ID。如果呼叫者需要这个数据，使UI编辑，然后调用者需要通过ID 23，也许加入成员{ID：23}，手动的JSON结果
在营＃1人还认为，在结果集中的ID的presence将表明，这个值可以修改的，当然它不能哪些。
CAMP＃2：如果没有ID，JSON结果集不能在本地UI形式用于编辑/更新操作。取而代之的是，AJAX回调机制必须负责将围绕ID字段和手动添加这些结果集。这似乎klunky而且容易出错。在UI家伙正在结果集感觉像它丢失的数据，应该是present，即ID的说法。
CAMP＃3：这些人都关心的一致性。如果我们曾经有由API返回的用户对象的集合，这些对象必须包括ID。因此，为了保持一致性，一个GET的单版本也应包括ID。
CAMP＃4：这些人都表明了用户的GET请求可能超媒体或SelfLinks的形式将包括ID返回元数据
这是不是一个深奥的谁是对的？的说法，无论是。我们采取的办法将决定我们的API的形状和影响的几个开发人员的工作负荷在新的几个星期。
这是见仁见智的问题，这是不是那种问题的那＃1爱看。在任何情况下，我会提供我的。
您正在返回一个对象或资源的状态重新presentation。的ID是重新presentation的一部分，因此，应该被包括在JSON分组。它是资源的属性。无论主叫知道ID与否并不特别相关的讨论。 CAMP＃1站不住脚。
您提高对集合点是非常相关的。是否有意义使用一个重新presentation为检索-1的操作，和用于检索-N操作另一个重presentation？我想不是。
然而，你面临的问题是更普遍的？ - 应包含在被传输到客户端的重新presentation哪些数据，以及在什么情况下在某些情况下，主叫方根本不关心的属性的显著子集。特别是在一个大的对象集被检索的场景 - 在成本传送的数据相比，基本通信成本较大的 - 你想优化什么运回。
所有足够成熟REST协议具有塑造返回的数据的能力。
有关示例，请参阅
- Facebook的图形API，<一个href=\"http://developers.facebook.com/docs/reference/api/\">http://developers.facebook.com/docs/reference/api/
- 的StackExchange API 2.0版 - 有一个过滤器的对象可以传递给precisely塑造获取返回的内容。
- CouchDB的API - 拥有的每个的观点，这决定了数据被返回的地图功能。它也有一个毯子查询参数，
include_docs，它指示服务器包括完整的对象或只是元数据。 （在某些情况下，您可能希望只是数据，而不是实际的数据的数量。）
Facebook允许你明确指定所需的字段。
该stackexchange API很有趣。他们已经定义了一个全新类型的对象，以支持整形。您可以使用API来定义一个过滤器并保存在服务器端。然后在您的查询您传递的过滤参数的过滤器的ID，而返回的对象重新presentations包括在过滤器中指定的所有属性。没有过滤你得到字段的默认子集。要获得全域你需要定义一个包容各方的过滤器。
您可以在 https://api.stackexchange.com/docs/answers
...具体请看筛选规范对话框。
有就是做事情没有唯一正确的方法。你需要平衡的塑造功能，你开发成本，将使用该API的应用程序的需要支持的复杂性。
A number of the developers here are having a friendly (some would say religious) discussion about whether a GET request from a RESTful API should return the ID of the requested resource. Let's assume the following GET request:
http://my.api.com/rest/users/23
This currently returns:
{"name": "Jim", "age": 40, "favoriteColor": "blue"}
Note that "id" is missing from the result set.
There are basically 4 camps battling with this issue.
CAMP #1: When callers make the GET request, they already know the ID. Therefore, the result set should not include the ID. If callers need this data to enable UI editing, then callers needs to pass through the ID 23, perhaps adding the member {"id": 23} to the JSON manually.
Folks in Camp #1 also argue that the presence of the ID in the result set would indicate that this value can be modified, which of course it can't.
CAMP #2: Without the ID, the JSON result set can't be used natively for edit/update operations in UI forms. Instead, the AJAX callback mechanism needs to be responsible for passing around ID fields and manually adding these to the result set. This seems klunky and error prone. The UI guys are making the argument that the result set "feels" like it's missing data that should be present, namely the ID.
CAMP #3: These folks are concerned about consistency. If we ever have a collection of user objects returned by an API, these objects MUST include the ID. Therefore, for consistency, the singleton version of a GET should also include the ID.
CAMP #4: These folks are suggesting that the GET request for a user could return meta data in the form of HyperMedia or SelfLinks that would include the ID.
This isn't an esoteric "Who's Right?" argument, either. The approach we take will dictate the shape of our API and affect the work loads of several developers over the new few weeks.
This is a matter of opinion, which is not the kind of Question that Stackoverflow loves to see. in any case, I will offer mine.
You are returning the representation of the state of an object or resource. The ID is part of that representation, and therefore ought to be included in the JSON packet. It is a property of the resource. Whether the caller knows the ID or not is not particularly germane to the discussion. CAMP #1 is on shaky ground.
The point you raise about collections is very relevant. Does it make sense to use one representation for the retrieve-1 operation, and another representation for the retrieve-N operation? I think not.
However, the issue you are confronting is more general - what data should be included in the representation that is transferred to clients, and under what circumstances? In some cases the caller simply does not care about a significant subset of the properties. Especially in scenarios where a large set of objects gets retrieved - where the cost to transmit the data is larger in comparison to the base communication cost - you'd like to optimize what is shipped back.
All sufficiently mature REST protocols have an ability to shape the returned data.
For examples, see
- the Facebook Graph API, http://developers.facebook.com/docs/reference/api/
- the StackExchange API v2.0 - there is a "filter" object you can pass to precisely shape what gets returned.
- the CouchDb API - has a map function for every view, which determines what data gets returned. It also has a blanket query parameter,
include_docs, which directs the server to include full objects or just metadata. (In some cases you might want only the count of the data, not the actual data.)
Facebook allows you to explicitly specify the fields you want.
The stackexchange API is interesting. They've defined an entirely new type of object to support the shaping. You can use the API to define a "filter" and save it on the server side. Then in your query you pass a filter param with the ID of the filter, and the returned object representations include all the attributes specified in the filter. With no filter you get a "default" subset of fields. To get "all fields" you need to define an all-inclusive filter.
you can see this in action at https://api.stackexchange.com/docs/answers
...and specifically see the filter specification dialog.
There is no single correct way to do things. You need to balance the complexity of the "shaping" feature you support with the cost to develop and the needs of the apps that will use the API.
这篇关于如果一个RESTful GET响应返回资源的ID？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
