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

Question

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

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

获取/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 响应？

Answer 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 中专门标识了该资源，并且感觉比将其作为参数更正确一些。原因是 params 应该是关于如何检索内容的修饰符，而不必改变您正在检索的不同资源。在您的情况下，由于每个版本都是不同的，因此明确解决资源似乎更合适。但是，即使这样也不会破坏任何 RESTful url 规则或概念，如果您问 10 个人，您可能会得到不同的答案:)

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