为 REST Api 服务器编码移动设备版本控制答案

【问题标题】：encoding mobile-device versioning for REST Api server为 REST Api 服务器编码移动设备版本控制
【发布时间】：2010-10-15 14:10:52
【问题描述】：

我们有基于 HTTP 的 restful api。在其他客户端中，我们还有移动设备客户端（例如 iphone）。问题是那里有几个不同版本的 iPhone 应用程序（1.0、2.0）。因为它们是分布式的，所以我们无法控制调用我们的应用程序版本。

为了在服务器端识别应用程序版本，我看到以下选项：

设备必须附加 URL 参数（例如 /foo?iphone-app-version=1.0）：有点恶心，但好消息是我总是可以在服务器日志中看到它（总是记录 URL）
我们使用 HTTP 摘要对 api-clients 进行身份验证。我们可以在用户名中编码应用程序版本（例如 iphone_1_0）：好在它记录在服务器日志中，但仅适用于作为 HTTP 摘要公开的资源。
设备必须使用自定义 HTTP 标头，例如X-IPHONE-APP-VERSION：在我看来是最干净的方法，但我们不会在服务器日志中记录 HTTP 标头（对于日志噪音，它已关闭）。所以后面的分析是不可能的。

您有首选方法或任何其他替代方法吗？

编辑：上面的版本控制不是指 api-versioning/content-negotiation。它是移动设备的版本。

【问题讨论】：

【解决方案1】：

您可以使用 Accept-Header 允许客户端通过识别它支持的媒体类型版本来声明它具有哪些功能。例如

移动应用可以：

GET /server/foo
Accept:  application/vnd.acme.fooappV1+xml

当您引入不向后兼容的新功能时，您可以告诉新更新的客户端发送，

GET /server/foo
Accept:  application/vnd.acme.fooappV2+xml

然后您的服务器知道它正在与之交谈的客户端的功能。您也可以让新客户这样做：

GET /server/foo
Accept:  application/vnd.acme.fooappV1+xml, application/vnd.acme.fooappV2+xml

这样您就可以慢慢地将服务器资源迁移到新格式。如果端点提供application/vnd.acme.fooappV1+xml，则客户端将恢复为旧方式。如果端点返回application/vnd.acme.fooappV2+xml，则新代码可以接管。

使用这种方法，无需更改任何 URI，因此书签和统计信息仍然有效。随着时间的推移，可以逐步迁移到新格式，并且可以逐步取消对旧客户端的支持。

【讨论】：

已经有了版本控制概念（通过标题和永久链接）。我需要的是识别移动设备应用程序版本。此版本与 api-server 版本不同。动机是了解最终用户使用了哪些应用程序发布/版本。
是的，这可能适合 (w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43)。到目前为止，我只看到此标头来识别“连接构建器”（例如 firefox、http-commons 客户端）。我将看看 iphone 当前正在发送什么用户代理条目。也许我只会将 app-version-fingerprint 附加到它（这类似于提到的 X-IPHONE-APP 标头）。缺点仍然是我无法在生产模式日志中看到它，因为它不包含在永久链接中。因此，过去日志中的任何统计信息仍然不起作用，只会显示临时打开的标题日志。
我决定不使用 User-Agent 标头，而是使用自定义 X-xxx-USER-AGENT 标头。主要原因是 User-Agent 已经被 http-client 库或移动设备信息“污染”了。自定义 X-xxx-USER-AGENT 更容易为服务器解析，并且不会干预经常设置它的 http-library，并且可以覆盖自定义条目。

【解决方案2】：

我决定使用自定义 X-xxx-USER-AGENT 之一。决定反对更标准的“用户代理”的主要原因是它已经被 http-client 库或移动设备信息“污染”。自定义 X-xxx-USER-AGENT 更容易为服务器解析，并且不会干预经常设置它的 http-library，并且可以覆盖自定义条目。

【讨论】：