REST API设计 - 查询邮件数据 - 选择哪种毒药？

Question

我们目前正在设计一个内部REST api.我们有以下用例:

1. 用户(109)想要读取他已经发送给另一个用户的消息(110)
2. 应用程序通过他在验证后收到的令牌凭证(在执行GET请求时)知道应用程序(109)
3. 我们假设在这个例子中,用户109是发送者,110是接收者

从用户的角度总结"给我(109)发送给110的邮件"

我们想到了以下URI,但我们无法决定采用哪一个:

a) GET http://localhost:9099/api/mails/109?receiverUserId=110
b) GET http://localhost:9099/api/mails?senderUserId=109&receiverUserId=110
c) GET http://localhost:9099/api/mails?receiverUserId=110
d) GET http://localhost:9099/api/mails/me/to/110 (when logged in as 109 via token credentials we know that "me" is 109)
f) GET http://localhost:9099/api/mails/109/to/110 (explicit request, e.g. for admins … has to be guarded against illegal access)

所有链接都是"上下文敏感的",即将一个链接发送到接收器(110)将产生执行GET请求的不同结果.

我想知道你对使用什么网址的看法.

任何帮助高度赞赏.

欢呼马塞尔

Answer 1

对于相同的URL ，对不同客户端的不同响应是可以的。

StackExchange 是这样做的：

GET /me/comments/{toid}

这是记录在这里。

推特也这么做了：

GET /statuses/home_timeline

这是记录在这里。

这两个 URL 都根据身份验证推断登录的用户。是的，如果用户共享缓存，它就会破坏缓存，但在我看来，这没关系。这是否打破了 REST 的“资源识别”约束可能是有争议的。这个问题的答案以及随后的评论向我展示了为什么它是有争议的。

事实上，在选项中，您确实提到了不“上下文敏感”的 URL：

GET /api/mails?senderUserId=109&receiverUserId=110

这个将始终返回从 109 到 110 的消息。但是，虽然一个客户端希望在查看“已发送”消息时看到此结果，但另一个客户端希望在查看“已接收”消息时看到此结果。有点奇怪啊？另外，在服务器上，您必须检查经过身份验证的用户是否为 109|110，否则抛出401 UNAUTHORIZED.

我会选择类似的东西：

GET /mail/sent

返回所有已发送的邮件。和：

GET /mail/sent?to=110 (like applying a 'filter' to /mail/sent)
OR
GET /mail/sent/110 (clean URL)

返回发送至 110 的邮件。