REST api中请求资源摘要表示的最佳方式？答案

【问题标题】：Best way in REST api to request a summary representation of a resource?REST api中请求资源摘要表示的最佳方式？
【发布时间】：2015-08-13 19:23:26
【问题描述】：

我有一个 REST api 可以处理大量资源，即客户。客户有时想要客户的缩写/摘要表示。指定请求是摘要表示的好方法是什么？

要获得客户 123 的完整代表，请访问：/customers/123

获取摘要表示是/customers/123/summary 的好方法吗？有更好的选择吗？

【问题讨论】：

标签： rest

【解决方案1】：

为了使您的解决方案可重用和灵活，我建议实施“过滤器”查询参数。在那里，您可以放置客户端所需的任何字段：

GET /customers/123?fields=id,first_name,last_name,email

这样，如果以后您需要为不同的任务创建不同的摘要，您将无需修改任何内容。

我不推荐/customers/123/summary，因为它不灵活。对于一种情况可能没问题，但如果客户端需要为不同的情况访问不同的属性，您将不得不调整资源（很可能通过返回比需要更多的字段）。如果您想“隐藏”字段名称，也许替代方法可能是这样的：

GET /customers/123?view=DESCRIPTION

其中“DESCRIPTION”将描述摘要的类型。例如：

GET /customers/123?view=addresses_only // eg. returns billing and home address
GET /customers/123?view=short // eg. returns only id, first name, last name

这仍然很灵活，因为您可以轻松创建新视图。

【讨论】：

感谢您的建议，我可以看到它是多么灵活。我对这种方法的一个担忧是它假设消费者知道客户资源的可用字段。
在这两种情况下，无论是 /summary 还是 /?field=...，您仍然需要与客户端共享一个 URL。如果您只是自己给他们提供 URL，他们就不需要知道可用的字段。我已经用另一种可能的解决方案更新了我的帖子。
只考虑?fields=... 增加的灵活性不是免费的。您正在扩展表面或 API，现在您需要验证（白名单）您公开的字段，您正在为客户端提供更多控制权，这有利有弊。
我喜欢这个想法，但我发现GET /customers/123?view=short 和/GET /customers/123/short 之间没有什么区别。两者都意味着获取数据的简短版本和要返回的字段可能会在任何一种方法中发生变化。我正在尝试为view 方法找到一个卖点。
我可以看到一个优点是您不必使用 view= 方法修改您的 API。如果你从 /short 开始并决定你需要 /addressed_only 然后 /full_names 你将继续修改你的 api，如果你有多个端点这样做，它会变得很大。