Rest API design: 如何为具有多个子资源的POSTing资源创建restful API？

Question

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

basicDetails：如价格、颜色等
图片：产品图片
评论：对该产品的评论

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

推荐哪种restful方法？

Answer 1

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

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

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

Rest API design: 如何为具有多个子资源的POSTing资源创建restful API？

Rest API design: How to create restful API for POSTing resource with multiple sub-resources?

rest

api

restful-architecture

api-design