分层 RESTful URL 设计

Question

我仔细阅读了有关此问题的问题，但仍然没有明确的答案。

我有一个应用程序，想要构建一个 RESTful API 来公开一部分信息。我有三个资源：

1. 用户
2. 报告
3. 照片

用户有报告，报告有照片。照片不能存在于报表之外，报表也不能存在于用户之外。

我根据我的要求设计了以下 URL

用户登录，服务器使用在所有 API 调用的标头中发送的令牌进行响应

GET example.com/api/

获取用户信息

GET example.com/api/users/{username}

获取所有用户报告

GET example.com/api/users/{username}/reports

获取报告的所有照片

GET example.com/api/users/{username}/reports/{report_id}/photos

添加照片

POST example.com/api/users/{username}/reports/{report_id}/photos

删除照片

DELETE example.com/api/users/{username}/reports/{report_id}/photos/{photo_id}

修改照片描述

PUT example.com/api/users/{username}/reports/{report_id}/photos/{photo_id}

问题

1. 在 URL 中添加资源 id 是否是一种好的做法，即资源/id，或者应该将其添加为查询参数？
2. 这种链接资源（即资源/id/子资源/id/等）的方法是否可以接受且良好，或者我应该将所有资源放在顶层并使用查询参数指定其位置？

Answer 1

这个设计没有错。但是这会创建很长的 URL，有时很难理解，并且 API 的用户需要了解层次结构。此外，API 的使用者需要以一点点非标准的方式编写更多代码（即使它可以完成，但会有点混乱）。从不同的角度思考这个问题
您拥有三个资源，每个资源都有自己的身份。因此，如果我们重构上述 URI，它将如下所示（我仅演示 GET）

用户资源：

获取用户列表

  GET example.com/api/users

获取特定用户

  GET example.com/api/users/{username}

报告资源：

获取所有报告

 GET example.com/api/reports

获取特定报告

 GET example.com/api/reports/{report_id}

照片资源

照片

GET example.com/api/photos

特定照片

GET example.com/api/photos/{photo_id}

用户 所有报告

GET example.com/api/reports?username={userName}

用户的特定报告

GET example.com/api/report?username={userName}&report_id={reportId}

用户 所有照片

GET example.com/api/photos?username={userName}

用户 报告 ID 的所有照片（如果 report_id 与用户无关，则您可能不需要用户名，这将进一步简化 URI）

GET example.com/api/photos?username={userName}&report_id={reportId}

所有 报告

GET example.com/api/photos?report_id={reportId}

这个简化了理解，并且可以使用这种方法在消费者端编写更标准的代码。

Answer 2

恕我直言，你建模得很好。

关于 1 我宁愿使用 resource/id 而不是查询参数。但建模时必须记住的一件事是代理的缓存机制等等。所以不要忘记标题。

我寻找用于过滤和排序的查询参数。

关于登录，凭据应位于标头中，不需要特定资源。只需根据资源安全性应用即可。

Answer 3

我不认为你的计划有什么问题。

现在大多数框架都使用类似的标准来指定 url（例如 Django）。

在我个人看来，它使 URL 更具可读性，对用户来说也更友好。