REST API 版本化

要管理应用接口业务逻辑的复杂性，需要你对API进行版本管理。版本控制可帮助你在需要变更服务逻辑时快速迭代。

随着系统业务发展或逻辑复杂度的不断提高，API的变化是不可避免的。 当变更会破坏现有系统客户端的集成时，管理这种变化的影响可能是相当大的挑战。

何时对REST API进行版本化

只有在重大破坏性变更发生时才考虑对API进行版本升级。破坏性变更包括：

• 一次或多次调用的响应数据格式发生了变化
• 响应数据类型发生变化（例如，将整数变为浮点数）
• 删除API返回数据的部分内

发生破坏性变更时，应该总是修改API的主版本号。

非破坏性变更（如添加新的REST端点或新的响应参数）不需要更改主版本号。

REST API 版本号如何定义

REST 没有提供任何关于API版本管理的指导规范，但是常用的实现方式有如下三种：

在URI上包含版本号

使用URI是最直接的方法（也是最常用的方法），尽管它违背了URI应该引用唯一资源的原则。 当版本更新时，您也可以保证客户端的集成。

例如：

http://api.example.com/v1
http://apiv1.example.com

版本号不必是数字，也不必使用v[x]这样语法指定。 替代方案包括日期，项目名称，季节或其他标识符，这些标识符对于产生API的团队来说足够有意义，并且随着版本的变化足够灵活地进行更改。

自定义请求头

自定义请求头（例如Accept-version）允许你在版本之间保留URI，尽管它实际上是现有Accept头实现的内容协商行为的重复。

例如：

Accept-version: v1
Accept-version: v2

使用请求头 Accept

内容协商可能让你保留一组干净的URL，但你仍然必须处理在某处放置不同版本内容的复杂性。 这种负担往往会被上移到您的API控制器，这些控制器负责确定要发送的资源版本。 最终结果往往是更复杂的API，因为客户端在请求资源之前必须知道指定哪些头。

例如：

Accept: application/vnd.example.v1+json
Accept: application/vnd.example+json;version=1.0

在现实世界中，API永远不会变的完全稳定。 因此，如何管理这一变化非常重要。 对于大多数API而言，详细记录API的变更信息和逐渐废弃API是可行的方法。