在 RESTful API 中访问对象的版本/修订

Posted 2023-03-31

【中文标题】在 RESTful API 中访问对象的版本/修订

【英文标题】：Accessing versions/revisions of an object in a RESTful API

【发布时间】：2012-10-04 23:29:10

【问题描述】：

在设计 RESTful API 时，我们遇到了如何访问“同一对象”的不同版本的问题。假设页面对象由唯一键标识并通过 GET /api/page/pagekey 访问。它可以通过发送 PUT /api/page/pagekey 和正文中的适当文档来更新。

现在我们的系统会跟踪页面的旧版本，我们也希望通过 API 访问这些旧版本。让我们假设文档的旧版本是版本 1。似乎至少有两种方法可以设计 API 来访问这个特定版本的页面：

GET /api/page/pagekey/1 GET /api/page/pagekey?version=1

第一个变体将特定版本呈现为自己的资源；第二个变体为现有资源提供了一个可选的版本上下文。

变体 (1) 或 (2) 是更好的解决方案吗？或者有更好的方法吗？ 在变体 (1) 中，请求不存在的版本号，例如/api/page/pagekey/7 可能会触发 HTTP 404 Not Found，这很方便。在考虑变体 (2) 时，这是否也是一个有效的状态响应，其中我们只更改现有资源的上下文“版本”，如果没有版本参数返回 HTTP 200 Ok 响应？

【问题讨论】：

我很好奇 - 你最后做了什么？

看起来我们会选择第二个变体（参数），尽管我个人更喜欢第一个，就像你一样。一个原因是我们的前端人员报告说主干 js 难以处理第一个变体。

有道理 - 考虑到 API id 的消费者绝对重要 :)

【参考方案1】：

每个资源 url 都应该是一个用于标识该资源的永久链接。

GET /api/page/id/rev

这当然是特定版本资源的永久链接。所以，没关系。但请注意，永久链接不要求内容随着时间的推移保持不变：

GET /api/page/id

这将返回最新的版本，这很好，并且会随着时间的推移而改变内容。为了进一步扩展，您甚至可以拥有像这样的时间资源并成为 RESTful：

GET /api/page/latest 

但是，/api/page/id?version=rev 也可以工作并且不会破坏任何 RESTful 概念。

我认为/id/rev 更纯粹一点，因为它在可寻址的 url 中专门标识了该资源，并且感觉比将其作为参数更正确。原因是参数应该是关于如何检索内容的修饰符，而不一定会改变您正在检索的不同资源。在您的情况下，由于每个版本都是不同的，因此明确解决资源似乎更合适。但是，即使那个没有违反任何 RESTful url 规则或概念，如果你问 10 个人，你可能会得到不同的答案:)

无论哪种方式，您都应该确保时间资源 /api/page/id 返回最新版本。

【参考方案2】：

根据定义，REST 几乎没有“相同对象”的概念。如果你在你的协议中需要这个，那么你需要有某种“标识符”。就这么简单;)

URL 参数是一种显而易见的方法。 "/1" 或 "?version=1" 肯定是两个不错的选择 - 您选择这只是一个偏好问题（以及您可能还想要多少“其他东西”的问题）。

无论哪种方式，您仍将不得不处理“未找到版本”类型的错误，并优雅地恢复。

恕我直言...