Rest API 设计：如何为具有多个子资源的 POSTing 资源创建 Restful API？答案

【问题标题】：Rest API design: How to create restful API for POSTing resource with multiple sub-resources?Rest API 设计：如何为具有多个子资源的 POSTing 资源创建 Restful API？
【发布时间】：2017-10-29 18:51:43
【问题描述】：

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

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

方法1：允许客户端通过单一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.
}

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

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

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

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

什么是推荐的restful方法？

【问题讨论】：

标签： rest api restful-architecture api-design

【解决方案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 - 会发送空值还是根本没有键？

【讨论】：