REST API版本控制

要管理这种复杂性，请修改API。版本控制可帮助您在识别所需更改时更快地进行迭代。

随着您对系统的知识和经验的改进，API的变化是不可避免的。当它有可能破坏现有的客户端集成时，管理这种变化的影响可能是一个很大的挑战。

何时进行版本控制

只有在进行重大更改时才需要对API进行升级。突破性变化包括：

  • 一个或多个调用的响应数据格式的变化
  • 响应类型的更改（即将整数更改为float）
  • 删除API的任何部分。

中断更改应始终导致更改API或内容响应类型的主版本号。

不间断更改（例如添加新端点或新响应参数）不需要更改主版本号。但是，在进行更改以跟踪可能正在接收缓存版本数据或可能遇到其他API问题的客户时，跟踪API的次要版本会很有帮助。

如何进行版本控制

REST不提供任何特定的版本控制指南，但更常用的方法分为三类：

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的详细记录和逐步弃用可能是可接受的做法。