RESTful API - 设计子资源

Question

我正在设计一个 RESTful API，我遇到了一个与子资源相关的问题。

我看到其他 API 使用完整的 URL 来操作子资源。以公司有部门和部门有员工为例。

一开始我考虑过实现所有可能的 URL。结果如下:

方法A

01. ### COMPANY URLS ###
02. DELETE /companies/{companyId}
03. GET    /companies/{companyId}
04. POST   /companies
05. PUT    /companies/{companyId}
06. 
07. ### DEPARTMENT URLS ###
08. DELETE /companies/{companyId}/departments/{departmentId}
09. GET    /companies/{companyId}/departments/{departmentId}
10. POST   /companies/{companyId}/departments
11. PUT    /companies/{companyId}/departments/{departmentId}
12. DELETE /departments/{departmentId}
13. GET    /departments/{departmentId}
14. PUT    /departments/{departmentId}
15. 
16. ### EMPLOYEE URLS ###
17. DELETE /companies/{companyId}/departments/{departmentId}/employees/{employeeId}
18. GET    /companies/{companyId}/departments/{departmentId}/employees/{employeeId}
19. POST   /companies/{companyId}/departments/{departmentId}/employees
20. PUT    /companies/{companyId}/departments/{departmentId}/employees/{employeeId}
21. DELETE /departments/{departmentId}/employees/{employeeId}
22. GET    /departments/{departmentId}/employees/{employeeId}
23. POST   /departments/{departmentId}/employees
24. PUT    /departments/{departmentId}/employees/{employeeId}
25. DELETE /employees/{employeeId}
26. GET    /employees/{employeeId}
27. PUT    /employees/{employeeId}

如您所见，有许多 URL 执行相同的操作。示例:08 是 12 的重复； 09 是 13 的重复； 17 是 21 和 25 的重复...

我想删除重复但保持一致性。因此，重新设计 API 时要牢记一个原则，sup-resources 可以，但 sub-sub-resources 不行。结果如下:

方法B

01. ### COMPANY URLS ###
02. DELETE /companies/{companyId}
03. GET    /companies/{companyId}
04. POST   /companies
05. PUT    /companies/{companyId}
06. 
07. ### DEPARTMENT URLS ###
08. DELETE /departments/{departmentId}
09. GET    /departments/{departmentId}
10. GET    /companies/{companyId}/departments
11. POST   /companies/{companyId}/departments
12. PUT    /departments/{departmentId}
13. 
14. ### EMPLOYEE URLS ###
15. DELETE /employees/{employeeId}
16. GET    /employees/{employeeId}
17. GET    /departments/{departmentId}/employees
18. POST   /departments/{departmentId}/employees
19. PUT    /employees/{employeeId}

我的问题

Q1。 方法 B 是否被认为是 RESTful？ (我假设是)

第二季度。假设还提供了文档，我应该考虑方法 B 是否存在陷阱？

如果您按照方法 B 指向其他 API，则可获得奖励积分。

编辑

Elad Tabak 提出了很好的见解。

我喜欢一些使用方法 B 的 API:

https://developers.google.com/youtube/v3/docs/

https://developer.github.com/guides/getting-started/

https://dev.twitter.com/rest/public

Answer 1

只要您不违反 chapter 5 中定义的 REST 约束，这两种方法都可以被视为 RESTful。罗伊·托马斯·菲尔丁的论文:

• Client-server
• Stateless
• Cache
• Uniform interface
• Layered system
• Code-on-demand

我看不到这两种方法的主要缺陷，但我更喜欢方法 B 而不是方法 A:URL 更短、更容易记住并且参数不多是必需的。

<小时/>

^{奖励积分: Spotify和 Facebook API 遵循这种方法。当然还有其他 API，但这些是我想到的。}