分层 RESTful URL 设计答案

【问题标题】：Hierarchical RESTful URL design分层 RESTful URL 设计
【发布时间】：2011-10-20 09:07:53
【问题描述】：

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

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

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

我根据自己的要求设计了以下网址

用户登录，服务器以令牌响应，令牌在所有 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}

问题

【问题讨论】：

我喜欢您所拥有的，但我很好奇您为什么不将照片和报告视为顶级资源。例如，/reports/{reportid}/authors /reports/{reportid}/photos /photos/{photoid}/authors /photos/{photoid}/reports。我了解您的限制，但只是好奇，为什么您不想从不同的入口点钻取数据。如果报告有多个作者怎么办 - 如果您有报告 ID 或标题但没有作者等怎么办。没有理由您不能有多个路径到同一资源，但我建议通知用户规范如果你这样做，每个的 URI。
旁注：Restful API 应该始终版本化（example.com/api/… vs. example.com/api/1/…），以便避免 URI 冲突与未来 API 更改。

【解决方案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}

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

【讨论】：

我喜欢你的例子。如果我想添加一张照片，在正文 json 中传递父（用户）的 id 是否正确？示例 POST example.com/api/photos { "id":"user_id_111","photo":"my_photo"}

【解决方案2】：

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

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

我使用查询参数进行过滤和那些排序。

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

【讨论】：

【解决方案3】：

我看不出你的方案有什么问题。

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

在我个人看来，它使 URL 更具可读性并且对用户来说更好一点。

【讨论】：