Web services 分层RESTful URL设计

我已经仔细阅读了关于这个问题的提问，但我仍然没有一个明确的答案

我有一个应用程序，希望构建一个RESTful API来公开信息的子集。我有三个资源：

使用者

报告

照片

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

我已经为我的需求设计了以下URL

用户登录时，服务器用令牌响应，令牌发送到所有API调用的头中

GET example.com/api/

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

获取用户信息

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

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

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

获取所有用户报告

GET example.com/api/

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

获取报告的所有照片

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

添加照片

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

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

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

删除照片

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

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}

问题

GET example.com/api/

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

在URL中添加资源id（即resource/id）是一种好的做法，还是应该将其作为查询参数添加

这种链接资源（即资源/id/子资源/id/等）的方法是否可以接受且良好，还是应该将所有资源放在顶层，并使用查询参数指定其位置

---

我看你的计划没有任何问题

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

---

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

我想你是如何很好地建模的

关于

1

我宁愿使用

资源/id

而不是查询参数。但是，在建模时必须记住一件事，即代理缓存机制等等。因此，不要忘记标题

我选择查询参数进行过滤和排序

---

关于登录，凭据应该在标题中，并且不需要特定的资源。只需应用每个资源的安全性。

这种设计没有错。但这会创建很长的URL，有时很难理解，API的用户需要知道层次结构。此外，API的使用者需要以一点非标准的方式编写更多的代码（尽管可以做到，但会有点混乱）。从另一个角度思考这个问题 您有三个资源，每个资源都有自己的标识

用户资源：

获取用户列表

  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?username={userName}

特定照片

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

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

使用报表id的所有照片（如果报表id是唯一的，则不考虑用户，则可能不需要用户名，这将进一步简化URI）

报告的所有照片

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

---

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

我喜欢您拥有的内容，但我很好奇为什么您不将照片和报告视为顶级资源。例如，/reports/{reportid}/authors/reports/{reportid}/photos/photoid}/authors/photos/{photoid}/reports。我理解您的限制，但只是好奇，为什么您不想从不同的入口点钻取数据。如果一个报表有多个作者该怎么办？如果您有一个报表ID或标题，但没有它的作者，等等。没有理由您不能有多个到同一资源的路径，但是如果您有，我建议将规范URI通知每个用户。旁注：Restful API应该始终进行版本控制（

example.com/api/…

vs.

example.com/api/1/…

）以避免URI与将来的api更改发生冲突。我喜欢您的示例。如果我想添加一张照片以在主体json中传递父（用户）的id是否正确？example POST example.com/api/photos{“id”：“User\id\u 111”，“photo”：“my\u photo”}