版本化RESTful服务？

Question

我在http://example.com/v1/SomeResource上部署了RESTful Web服务。 有一天，新的协议版本（ 不向后兼容 ）被部署到http://example.com/v2/SomeResource 。 从客户端看，此升级可能在两个HTTP请求之间的任何时间发生。

服务器如何向客户端指示它不再支持v1调用，并且客户端应该升级到v2？ 我可以使用适当的响应代码吗？

我想向客户提供以下信息：

1. 发生了不兼容的升级。 客户端无法使用新服务，因为协议可能完全不同。
2. 新客户端软件的URL。
3. 向用户解释他们必须升级的消息。

Answer 1

我推荐Peter Williams的以下文章

• 版本控制REST Web服务

Answer 2

最佳实践：

最好将版本控制保留在URL之外，并使新资源向后兼容旧版本。

向后兼容：

如果您必须将v1保留在URL中，并且正在制作v2 URL，那么您必须决定是否要支持这两种格式，或者使旧的v1过时。 如果您决定使旧的v1过时，那么我建议为请求v1 URL的任何人返回303或401。

使旧网址过时：

我建议使用303见其他。 或者，如果没有关联的重定向，则使用410 Gone。

资源

303见其他

可以在不同的URI下找到对请求的响应，并且应该使用该资源上的GET方法检索。 此方法主要用于允许输出POST激活的脚本以将用户代理重定向到选定的资源。 新URI不是最初请求的资源的替代引用。 303响应绝不能被缓存，但对第二个（重定向）请求的响应可能是可缓存的。

不同的URI应该由响应中的Location字段给出。 除非请求方法是HEAD，否则响应的实体应该包含一个带有指向新URI的超链接的短超文本注释。

注意：许多pre-HTTP / 1.1用户代理不了解303状态。 当考虑与这样的客户端的互操作性时，可以替代地使用302状态代码，因为大多数用户代理对302响应做出反应，如针对303所描述的。

记录一切：

需要关注的主要问题是您选择返回的内容，只需在文档中记录即可。 您可以决定服务的工作方式，其他想要使用它的人也会遵循文档。

Answer 3

我认为你不应该首先这样做，但可能为时已晚。

URI也应该是静态的，以便在资源更改或服务实现发生更改时，链接保持不变。 这允许书签。 在URI中编码的资源之间的关系保持独立于存储它们的关系的方式也很重要。

从文章RESTful Web服务：基础知识 。

Answer 4

我建议改为使用301（301 Moved Permanently）。 了解原因 。

希望它有所帮助，Bruno Figueiredo