REST 风格的 API : How to organize nested resources

Question

我对如何组织 API 路由结构有疑问。阅读了许多关于构建 RESTful API 的书籍，但找不到答案。每本书都讲述了简单的 CRUD 操作和一个级别的嵌套资源。像 /users 和 /users/1/posts。没问题。

示例:

但让我们看看更困难的现实生活示例:

GET /cars // List of cars
GET /cars/{car_id} // Get single car
POST /cars // Add new car
PUT /cars/{car_id} // Update existing car
DELETE /cars/{car_id} // Delete car by specified ID

cars 的数据库表结构为

Table "cars"
    - id
    - uuid
    - make
    - model
    - year
    - created_at
    - updated_at
    - deleted_at

到目前为止没有问题，但我需要添加嵌套资源。使用指定汽车完成的所有维修。

GET /cars/{car_id}/repairs // List of repairs that were done with car
GET /cars/{car_id}/repairs/{repair_id} // Get single repair
POST /cars/{car_id}/repairs // Add new repair for specified car
PUT /cars/{car_id}/repairs/{repair_id} // Update existing repair for specified car
DELETE /cars/{car_id}/repairs/{repair_id} // Delete repair by specified ID

数据库表的结构是

Table "car_repairs"
    - id
    - uuid
    - car_id ( foreign key to cars )
    - title
    - description
    - repair_started_at
    - repair_ended_at
    - created_at
    - updated_at
    - deleted_at

到目前为止没有问题。就像在所有的书中一样。 /users 路由和嵌套路由 /users/1/posts。但是当我需要添加另一层嵌套时，问题就来了。

我需要 CRUD 路线来处理汽车维修时发现的所有缺陷

GET /cars/{car_id}/repairs/{repair_id}/defects // List of all defects that were found for specified repair for speicified car
GET /cars/{car_id}/repairs/{repair_id}/defects/{defect_id} // Get single defect
POST /cars/{car_id}/repairs/{repair_id}/defects // Add new defect
PUT /cars/{car_id}/repairs/{repair_id}/defects/{defect_id} // Update existing defect
DELETE /cars/{car_id}/repairs/{repair_id}/defects/{defect_id} // Delete existing defect

表结构为:

Table "car_repair_defects"
    - id
    - uud
    - car_id
    - repair_id
    - name
    - description
    - created_at
    - updated_at
    - deleted_at

问题:

这里要做什么，.../defects 的水平是否正常？

考虑我是否需要添加另一个第 4 层嵌套的情况，例如，用于发现缺陷的所有部件

在 RESTful API 中嵌套资源时的最佳实践

可以说不用嵌套也可以做到这一点。示例 /cars /repairs /defects /parts 但是，带有嵌套资源的 RESTful 示例呢？那么嵌套资源0,1,2,3的最大层数是多少？

此外，如果不使用嵌套就可以完成，例如，您需要创建字典路径 /defects，它只列出所有可能的汽车缺陷。所以会有名称冲突。

此外，如果没有嵌套，您将如何过滤使用嵌套过滤的项目？

defects?car_id=1&repair_id=2&defect_id=3

像这样？这看起来很难看。

请有人指点一本书或一篇文章，或者给出关于最大嵌套级别和前面列出的问题的答案。谢谢。

Answer 1

这里是关键点:REST 不关心您对标识符使用什么拼写。

也就是说，REST 认为这些 URI 中的每一个都同样好。

/cars/{car_id}/repairs/{repair_id}/defects
/08617423-cc74-4967-9a67-49e4171f01b7

就客户端而言，标识符是不透明的；将信息编码到 URI 中由服务器自行决定以供其独占使用。

除此之外，标识符拼写约定是有效的代码风格约定；使用符合本地风格的拼写。

从客户端的角度来看，标识符不描述资源的语义；这就是超媒体表示的工作。