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

Question

因此，RESTful API 的一般模式是返回带有嵌入链接的单个对象，您可以使用它来检索相关对象。但有时为了方便起见，您希望一次拉回整个对象图。

例如，假设您有一个带有 的商店应用程序。客户 , 订单 , 和 返回 .您希望将客户 ID 12345 的个人信息、所有订单和所有退货一起显示。(大概有充分的理由不总是退回订单和带有客户个人信息的退货。)

纯粹的 RESTful 方法是这样的:

GET /

返回一个链接模板列表，包括一个用于查询客户的链接模板

GET /customers/12345 (基于来自 / 的链接模板)

返回客户个人信息

返回链接以获取该客户的订单并返回

GET /orders?customerId=12345 (来自 /customers/12345 回复)

获取客户12345的订单

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 并且将像一个一样运行。