父>子元素调用的 API 约定

Question

我们正在试图弄清楚是否有一种普遍接受的方式来提供API父->子资源。假设我们有一个Person实体，并且每个Person都有由Address实体表示的0个或多个地址。

就基本API而言，我们将拥有：

POST:    /api/v1/person
GET:     /api/v1/person/{id}
PUT:     /api/v1/person/{id}
DELETE:  /api/v1/person/{id}

然后我们有两种方法来检索一个人的地址：

1. /api/v1/person/{id}/addresses
2. /api/v1/addresses/{personId}

我们觉得为GET选择前一个选项/person/{id}/addresses更自然，但同时，如果我们想通过id检索地址，它应该是/api/v1/address/{id}。

问题是，在处理POST、PUT和DELETE调用时是否有约定？对我来说，这些应该被调用到/api/v1/address OR /api/v1/address/{id}的地址服务是有道理的，但同时我也明白为什么有人会POST到"/api/v1/person/{id}/address"，而不是在请求体中传递person-id。

所以，是的，你们能为我们指明正确的方向吗？在API设计中，当涉及到父母关系时，有成文或不成文的规则吗？

提前感谢！

Answer 1

一个地址可以在没有人的情况下存在吗？如果答案是肯定的，那么地址应该是它自己的资源。

• /api/v1/addresses：所有地址的集合
• /api/v1/addresses/{addressId}：单个地址
• /api/v1/addresses?person={personId}：一个人的所有地址

我不会使用/api/v1/addresses/{personId}，因为personId是一个人的ID，而不是地址的ID，这一点并不明显。

但与此同时，/api/v1/person/{id}/addresses应该可以从一个人导航到他的所有地址。

如果一个地址没有人就不可能存在，只使用/api/v1/person/{id}/addresses。