如何处理通常在 REST 中相互请求的两个资源？

Question

假设我有三个models/tables：备注、装运和用户。我想请求发货页面，但我需要来自特定用户的相关注释（文本、图像等）的信息。

处理此问题的最佳方法是什么？

我是否应该像 /api/shipment/note 一样创建嵌套资源并向其中添加查询参数以指定用户 ID、页面大小等？（像 /api/shipment/note 这样的嵌套资源是有效的 REST 吗？我看到像 /api/note/{noteid}/shipment 这样的东西是有效的，但是如何组队得到所有的东西）

或者我应该请求/api/shipment的所有货件（在查询参数中指定用户）并请求/api/note/{noteid}的每个货件的备注信息？

或者我应该使用 /api/user/{userid}/shipment/note？

或者因为我很少会在没有注释信息的情况下请求发货资源，我是否应该将注释信息添加到 /api/shipment 端点？

Answer 1

如果您的用例要求您同时查询货件和票据，那么合并调用会更高效。这也假设两组数据来自同一个数据存储。

为了处理不需要 note 数据的情况，您可以引入详细级别或 include 查询字符串参数来标识应包含的额外数据。

api/shipment?include=note|foo|bar

或

api/shipment/{id}?include=note

Answer 2

基于 here.

的答案的更多可能性

a) 使用自定义媒体类型:

GET /api/shipments HTTP/1.1  
Host: example.com  
Accept: application/vnd.company.full+json

信用：

b) 使用新的特定于内容的端点:

/api/shipments/withNotes

信用：

c) 作为组合资源

这基本上是 b) 但有一个转折：

/api/shipmentsWithNotes

这是因为它具体化了连接的概念as a noun。

如何处理通常在 REST 中相互请求的两个资源？

How to handle two resources that are generally going to be requested with each other in REST?

api

rest

api-design