在RESTful API中包含/嵌入与链接

Question

因此，RESTful API的一般模式是返回一个带有嵌入式链接的对象，您可以使用它来检索相关对象。但有时候为了方便起见，你想立刻撤回一大块对象图。

例如，假设您的商店应用程序包含客户，订单和返回。您希望一起显示客户ID 12345的个人信息，所有订单和所有退货。（大概有充分的理由不总是返回订单并返回客户个人信息。）

纯粹的RESTful方式是这样的：

1. GET /
   • 返回链接模板列表，包括一个用于查询客户的链接模板
2. GET /customers/12345（基于/的链接模板）
   • 返回客户个人信息
   • 返回链接以获取此客户的订单并返回
3. GET /orders?customerId=12345（来自/customers/12345回复）
   • 获取客户12345的订单
4. GET /returns?customerId=12345（来自/customers/12345回复）
   • 获取客户12345的退货

但是，一旦你拥有customers URI，就可以在一个查询中将其全部拉回来。这种便利性查询是否有最佳实践，您希望转换部分或全部链接而不是发出多个请求？我想的是：

GET /customers/12345?include=orders,returns

但是，如果有人采用这种方式，那么我宁愿做一些事情。

（FWIW，我不是在建一个商店，所以我们不要狡辩这些是否是模型的正确对象，或者你将如何深入到实际的产品，或其他什么。）

---

已更新以添加：在HAL speak中看起来这些被称为“嵌入资源”，但在显示的示例中，似乎没有任何方法可以选择哪些资源镶嵌。我发现one blog post建议使用embed作为查询参数，如上所述：

GET /ticket/12?embed=customer.name,assigned_user

这是一种标准的还是半标准的做法，还是一个博主组成的东西？

Answer 1

因为必须为支持它们的每个链接关系记录这些类型的参数的语义，并且这或多或少是你必须编写代码的东西，我不知道有什么东西通过一种标准的表达方式获得收益。 URL结构更可能是由服务器返回的最简单或最谨慎的驱动，而不是任何特定的标准或最佳实践。

也就是说，如果你正在寻找灵感，你可以查看OData正在使用$expand parameter做什么，并建立你的链接关系。请记住，您仍然应该清楚地定义关系的合同，否则客户端程序员可能会看到类似OData的约定并且（错误地）假设您的应用程序完全符合OData并且表现得像一个。