分层RESTful URL设计

Question

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

我有一个应用程序,并希望构建一个RESTful API来公开信息的子集.我有三个资源:

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

用户有报告和报告都有照片.报告不能存在于报告之外,报告不能存在于用户之外.

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

用户登录,服务器使用令牌进行响应,该令牌在所有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而不是查询param.但是在建模时必须考虑的一件事是代理的缓存机制等等.所以不要忘记标题.

我去查询参数用于过滤和那些排序.

关于登录,凭据应位于标头中,并且不需要特定资源.只需应用每个资源安全性.