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

Question

在设计RESTful API时,我们遇到了如何访问"同一对象"的不同版本的问题.让我们说一个页面对象由唯一键标识,并由GET/api/page/pagekey访问.它可以通过发送PUT/api/page/pagekey和正文中的相应文档来更新.

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

1. GET/api/page/pagekey/1
2. 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}它有点纯粹,因为它专门识别可寻址网址中的资源,并且感觉比把它变成一个参数更正确.原因是params应该是关于如何检索内容的修饰符,而不一定要改变你正在检索的不同资源.在您的情况下,由于每个版本都是不同的,因此更清楚地解决资源似乎更合适.但是,即使那个没有破坏任何RESTful网址规则或概念,如果你问10个人你可能得到一个不同的答案:)

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

Answer 2

几乎根据定义，REST 没有“同一对象”的概念。如果您的协议中需要这个，那么您将需要某种“标识符”。就如此容易 ;）

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

无论哪种方式，您仍然必须应对“版本未找到”类型的错误，并优雅地恢复。

恕我直言...