在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的退货

但是,一旦你拥有了customersURI,它就能很好地将它全部拉回到一个查询中.这种便利性查询是否有最佳实践,您希望转换部分或全部链接而不是发出多个请求？我想的是:

GET /customers/12345?include=orders,returns

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

(FWIW,我不是在建一个商店,所以我们不要狡辩这些是否是这个模型的正确对象,或者你将如何深入到实际的产品或其他任何东西.)

---

更新添加:看起来在HAL中说这些被称为"嵌入式资源",但在所示的示例中,似乎没有任何方法可以选择嵌入哪些资源.我找到一篇博文,建议像我上面描述的那样,embed用作查询参数:

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

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

Answer 1

由于这些类型的参数的语义必须为支持它们的每个链接关系进行记录，并且这或多或少是您必须编码的内容，我不知道有什么好处有一个表达这一点的标准方式。URL 结构更有可能由服务器返回的最简单或最谨慎的内容驱动，而不是任何特定的标准或最佳实践。

也就是说，如果您正在寻找灵感，您可以查看 OData 使用$expand 参数执行的操作，并从中建立链接关系模型。请记住，您仍然应该明确定义关系的契约，否则客户端程序员可能会看到类似 OData 的约定，并（错误地）假设您的应用程序完全符合 OData 且行为类似。