API - 我需要父资源吗？答案

【问题标题】：API - do I need the parent resource?API - 我需要父资源吗？
【发布时间】：2023-01-08 18:25:09
【问题描述】：

一个person可以有多个reviews。我到 CREATE 一个新的 review 的端点是：

post /person/{id}/reviews

UPDATE评论的端点怎么样？我看到两个选项：

坚持父资源：patch /person/{person_id}/reviews/{id}
只有在 URI 中有评论：patch /reviews/{id}
我可以在使用它们中的任何一个时被卖掉：
1. 与之前定义的端点一致，但不需要{person_id}。
2. 这是“高效”的，因为我们没有指定实际上不需要的参数 ({person_id})。但是，它打破了 API 约定。
  哪一个更好，为什么？

【问题讨论】：

标签： api rest

【解决方案1】：

客户根本不必知道 ID。客户创建评论后，响应应包含新评论的 URI，如下所示：

HTTP/1.1 201 Created
Location: /person/4/reviews/5

客户现在拥有评论的完整 URL，使其完全无关评论的外观和此处包含的信息。

不要忘记 URL 本身是一个创建全球唯一 ID 的系统，它不仅嵌入了它自己的唯一标识，还嵌入了有关如何访问数据的信息。如果您引入一个单独的“id”和“person_id”字段，您就没有利用网络应该如何工作。

【讨论】：

感谢你的回答。如果客户不知道评论 URL，我想每个评论的 URL 都必须包含在评论 INDEX 中，对吗？关于全球唯一的 ID - /reviews/5 和 /person/4/reviews/5 都是全球唯一的。你为什么会选择后者？
因此，您建议通过正文参数发送 person_id 作为初始 POST 请求？然后使用 Location 更新对这个人的评论：/person/4/reviews/5？都是因为您不想通过 URL 公开 ID？只是想重申你的想法，看看我是否理解正确。
@RichSteinmetz 在这个问题中，person_id 是路径的一部分，因此服务器应该能够通过此上下文找出它。
可能只有我一个人，但我仍然不明白这个答案与 OP 的设计相关问题有什么关系，所以我创建了一些我希望作为讨论点的东西：stackoverflow.com/a/75047010/5925094

【解决方案2】：

在 API 设计方面，在不了解 OP 情况的太多细节的情况下，我会沿着这些指南走：

只有 URI 中有评论：patch /reviews/{id} 这是“高效”的，因为我们没有指定参数 ({person_id}) 那不是真的需要。但是，它打破了 API 约定

“效率”允许更灵活的设计。此时没有现有的 API 约定被打破。此外，这种方法使您可以灵活地避免在显示项目时总是需要父资源 ID。

坚持父资源：补丁 /person/{person_id}/reviews/{id} 它与之前定义的端点一致，但 {person_id} 不需要。

这里的一致性方面可以忽略不计。仅仅因为以前的端点是以某种方式设计的，就将端点设计得与其他端点相似是没有好处的。

决定一种方式或另一种方式的关键是您传达的意图以及对端点施加的以下限制。

这里的关键问题是：

reviews 可以单独存在还是他们总是有父级 person？

如果您不确定，请选择更灵活的设计：PATCH /reviews/{id}

如果你确实知道它总是会绑定到一个特定的人，并且永远不会在数据库中有 person_id 的 null 值，那么你可以将它直接嵌入到你的端点设计中：PATCH /person/{person_id}/reviews/{id}

顺便说一句，其他端点也是如此，比如创建端点POST /person/{person_id}/reviews/{id}。拥有这样的端点会消除在没有人的情况下创建评论的灵活性，这可能是可取的，也可能不是。

【讨论】：