Rest API 设计：如何为具有多个子资源的 POST 资源创建restful API？

Question

我们是一个电子商务网站，并希望创建 API 为我们所有的客户提供一个接口，以通过此 API 发送产品相关信息。 我们目前需要 3 种类型的产品信息：

• 基本信息：如价格、颜色等。
• 图片：产品图片
• 评论：对该产品的评论

方法一：允许客户端通过单个 API 发送所有信息。

/api/product/
{
    "basicDetails" : {}, //json with all basic details of the product.
    "images": {}, //json containing array of images of the product.
    "reviews": {} //json containing array of reviews of the product.
}

方法二：为所有子资源创建不同的 API。

/api/product/basicdetails/
/api/product/images/
/api/product/reviews/

方法 3：为所有具有分层 URI 的子资源创建不同的 API。

/api/productBasicDetails/
/api/productImages/
/api/productReviews/

推荐哪种宁静的方法？

Answer 1

如果images和reviews都是产品不可或缺的一部分，如果没有这些存在，产品就不能存在，我会采用方法 1，因为在方法 3 中，您定义了许多用户可能会发现不清楚如何使用它们的端点。

否则，方法 2 似乎是最好的，也是最清晰的一种。 让您的客户创建具有所有基本细节的产品。 为响应该POST请求，应发送201 Created以及包含指向新创建资源的 URL 的Location标头。 然后编辑产品本身，直接发送请求/api/product/{id}/ 。 要更新/删除/创建子资源（即image或review ），请分别向/api/product/{id}/images/或/api/product/{id}/reviews/发送适当的请求。 通过这种方式，您将拥有清晰的关注点分离以及易于理解和一致的 API。 如果添加了任何其他资源，您仍然在单个根端点区域而不是多个（如方法 3 中所示）中操作。

此外，方法 1 的缺点是主体可能难以为客户端构建 - 例如可选images - 是否会发送空值或根本没有密钥？