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

Question

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

• 基本细节：如价格、颜色等
• 映像：产品映像
• 评论：该产品的评论

方法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/

Answer 1

如果images和reviews都是产品的组成部分，并且如果没有这些存在，产品就不可能存在，那么我会选择方法1，因为在第3中，您定义了许多endpoint，用户可能会发现这些endpoint不清楚如何使用它们。

否则，方法2似乎是最好的，也是最清楚的一个。让您的客户创建产品的所有基本细节。响应该post请求，应将201 created与包含指向新创建资源的URL的location头一起发送。然后要编辑产品本身，直接发送请求/api/product/{id}/。要更新/删除/创建子资源（即image或review)，请分别向/API/product/{id}/images/或/API/product/{id}/reviews/发送相应的请求。这样，您就可以清晰地分离关注点，并使用易于理解和一致的API。如果添加了任何其他资源，您仍然在单个根endpoint区域中操作，而不是在多个根endpoint区域中操作（如方法3所示）。

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