版本控制 RESTful 服务? [英] Versioning RESTful services?

问题描述

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

I have a RESTful web service deployed at http://example.com/v1/SomeResource. One day, a new protocol version (that is not backwards compatible) is deployed to http://example.com/v2/SomeResource. From the client of view, this upgrade could occur at any time between two HTTP requests.

服务器如何向客户端表明它不再支持 v1 调用并希望客户端升级到 v2?是否有我可以使用的适当响应代码?

How does the server indicate to the client that it no longer supports v1 calls and the client is expected to upgrade to v2? Is there an appropriate response code I can use?

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

I would want to provide the client with the following information:

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

推荐答案

最佳实践:

最好将版本控制排除在 URL 之外，并使新资源向后兼容旧资源.

It's probably better to keep the versioning out of the URL and to make the new resources backwards compatible with the old.

向后兼容:

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

If you must keep the v1 in the URL, and are making v2 URLs, then you have to decide whether you want to support both formats, or make the old v1 obsolete. If you decide on making the old v1 obsolete then I would recommend to return 303 or 401 for anyone requesting a v1 URL.

过时的旧网址:

我建议使用 303 See Other.或者，如果没有关联的重定向，则使用 410 Gone.

I would recommend using 303 See Other. Or if there is no associated redirect, then use 410 Gone.

来源

303 查看其他

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

The response to the request can be found under a different URI and SHOULD be retrieved using a GET method on that resource. This method exists primarily to allow the output of a POST-activated script to redirect the user agent to a selected resource. The new URI is not a substitute reference for the originally requested resource. The 303 response MUST NOT be cached, but the response to the second (redirected) request might be cacheable.

不同的URI应该由响应中的位置字段.除非请求方法是 HEAD，响应的实体应该包含一个简短的超文本注释指向新 URI 的超链接.

The different URI SHOULD be given by the Location field in the response. Unless the request method was HEAD, the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s).

注意:许多 HTTP/1.1 之前的用户代理不理解 303地位.当与此类客户端的互操作性是一个问题时，可以使用 302 状态码来代替，因为大多数用户代理都会做出反应到 302 响应，如此处针对 303 所述.

Note: Many pre-HTTP/1.1 user agents do not understand the 303 status. When interoperability with such clients is a concern, the 302 status code may be used instead, since most user agents react to a 302 response as described here for 303.

记录一切:

需要关注的主要事情是您选择返回的任何内容，只需将其记录在您的文档中即可.你可以决定你希望你的服务如何工作，其他想要使用它的人将遵循文档.

The main thing to be concerned about is whatever you chose to return, just document it in your documentation. You can decide how you want your service to work, others that want to consume it will follow the documentation.

这篇关于版本控制 RESTful 服务?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！