嵌套关系是否应反映在JSON API的URL中？

Question

我正在尝试遵循JSON API.我需要公开对嵌套资源的CRUD访问:产品评论.

在使用JSON API之前,我希望有一个这样的REST接口:

GET    /products/:product_id/reviews     - list reviews for a product
POST   /products/:product_id/reviews     - add a review for a product
PATCH  /products/:product_id/reviews/:id - update a review for a product
DELETE /products/:product_id/reviews/:id - delete a review for a product

我在规范中看到一些像这样的嵌套结构:

例如,照片评论的网址将为:

/photos/1/comments

但我不确定这种结构是否适合所有行动.

一方面,POST /products/:product_id/reviews如果我要在评论数据下指定POST主体中的产品,那么创建似乎是多余的relationships.

另一方面,如果在删除评论时指定产品ID很有用(可能不是),那么这DELETE /products/:product_id/reviews/:id似乎是唯一理智的方式; 人们争论是否允许请求正文进行DELETE请求.

我可以为一些请求而不是其他请求嵌套:

GET    /products/:product_id/reviews  - list reviews for a product
POST   /products/:product_id/reviews  - add a review for a product
PATCH  /reviews/:id                   - update a review
DELETE /reviews/:id                   - delete a review

但这似乎奇怪地不一致.

我永远不会窝:

GET    /reviews     - list reviews for the product specified in params
POST   /reviews     - add a review for the product specified in params
PATCH  /reviews/:id - update a review
DELETE /reviews/:id - delete a review

但这似乎很尴尬,似乎与我从文档中提出的第一个引用不符.

使用JSON API时,嵌套资源关系是否应反映在URL中？

Answer 1

我真的很喜欢你的问题,因为我一直有同样的想法.我很困惑,还没有人留下答案.

我一直在生产系统上使用JSON API一年多,我想给我两分钱.

首先,当我启动将要使用JSON API的项目时,我对嵌套与非嵌套资源存在疑问.然后,我遇到了嵌套资源的问题,这些问题可以通过非嵌套资源来避免.

要采用与示例中相同的路径,请考虑GET /products/:product_id/reviews端点.如果这样做,将评论嵌套在产品下是非常有意义的,因为我们最初在产品的上下文中显示评论.一切都是好的.

然后我们想在前端构建一个页面,显示用户和用户创作的所有评论.虽然我们已经有了获得评论的终点,但我们必须建立一个新的终点,例如GET /users/:id/reviews.

如果我们只是将第一个端点置于GET /reviews过滤器上?filter[product_id]=:id,我们可以向该端点添加一个新的过滤器,这对IMO来说很有意义.

我确实使用嵌套资源,但仅限于单例资源,GET /users/:id/email_settings以及其他一些有意义的特殊情况.

根据我的经验,如果将每种资源视为独立于其他资源,则将来会更容易.资源之间存在资源和关系.没有资源"拥有"API上下文中的另一个资源(在业务逻辑的上下文中,这是另一个故事).

我已经使用过这个策略,但在向现有端点添加新功能和添加新端点时,它仍然让我感到惊讶.