Github 糟糕的 REST API 设计

Posted 2023-02-21

【中文标题】Github 糟糕的 REST API 设计

【英文标题】：Github Bad REST API Design

【发布时间】：2021-10-09 15:07:15

【问题描述】：

我在研究 Github 的 REST API 时偶然发现了一些奇怪的 URL。 Github 有两个主要资源 /user 和 /users，其中 /user 指的是经过身份验证的用户， /users 指的是任何特定的用户。

这不违反 URN 的定义吗？主要是因为这两点：

有两个不同的标识符引用同一个实体。 /user 并不唯一代表一个资源，但即使针对成功的请求，也会对每个人给出不同的响应。

【参考方案1】：

有两个不同的标识符引用同一个实体。

这是完全有效的 - 见 Fielding, 2000;有许多不同的资源具有重叠甚至等效的表示是完全正常的，当然这些表示可能是使用来自公共实体的信息产生的。

当然，需要权衡取舍 - this 资源成功处理不安全请求不会使 that 资源的缓存响应无效；见RFC 7234。

/user 并不唯一地代表一个资源，但即使针对成功的请求，也会对每个人给出不同的响应。

这个比较乱。

TL;DR 版本在 HTTP 中是可以的，因为我们对 caching responses to authenticated requests 有特殊规则。

更长的版本是我们已经有了一个概念，即单个资源可能具有多个有效表示；我们可以使用主动或被动content negotiation 来确定在对客户端的响应中包含哪种表示，我们有Vary 标头来帮助缓存了解何时可以重用响应，等等。

XML 文档和 JSON 文档应该是两个不同的资源吗？还是同一资源的两种不同表示？英文文档和法文文档应该是两种不同的资源还是同一资源的两种不同表示形式？

在某些情况下，“同一资源的不同表示”答案是有意义的，因此“给出不同的响应”不一定是向下检查。

当然，授权不仅仅是内容协商，就像 Accept 和 Accept-Language 一样。所以我们有特殊的规则：

无需在 Vary 中发送 Authorization 字段名称，因为跨用户的重用受到字段定义的限制 -- RFC 7231

---

总之，这肯定是一种允许的设计。它是否也是一个好的设计将部分取决于他们需要满足的约束集合。

在设计审查中，如果没有必要的约束，我会拒绝 Github 设计 - 在我看来，关于 Alice 的文档和关于 Bob 的文档是不同的资源（改变一个不会改变另一个），并且应该清楚地标明。

但如果设计师被如此束缚？发货吧。