如何对API进行版本化?
嘻嘻发布于2023-04-17
浏览随着公司业务规模的不断扩大和业务深度的不断扩展,是必会导致技术团队API的不断变化,当这一变化会破坏现有客服端集成时,如何管理API的接口将是一个极大的挑战。对API进行版本化当在API中识别出所需的更改时,版本控制可以帮助我们更快地迭代。
何时版本化?
只有在做出重大更改时,API才需要更新版本
重大变化包括:
- 一个或多个呼叫的响应数据格式的更改
- 请求或响应类型的更改(即将整数更改为浮点)
- 删除API的任何部分。
更新API的版本时要能够保证API之前的版本是可用的。
如何版本化?
API接口化通常有三种方式:
URI版本控制
使用URI是最直接的方法(也是最常用的方法),尽管它确实违反了URI应该引用唯一资源的原则。您还可以保证在更新版本时中断客户端集成。版本不需要是数字,也不需要使用“v[x]”语法指定。
备选方案包括日期、项目名称、季节或其他标识符,这些标识符对生产API的团队来说足够有意义,并且足够灵活,可以随着版本的变化而变化。
使用自定义请求标头进行版本控制
自定义标头(例如Accept版本)允许您在不同版本之间保留URI,尽管它实际上是现有Accept标头实现的内容协商行为的副本。
使用“Accept” header
可以让您保留一组干净的URL,但您仍然需要处理在某个地方提供不同版本内容的复杂性。
这种负担往往会向上转移到API控制器上,这些控制器负责确定要发送的资源的版本。
结果往往是一个更复杂的API,因为客户端在请求资源之前必须知道要指定哪些标头。
Accept: application/vnd.example.v1+json
Accept: application/vnd.example+json;version=1.0
在现实世界中,API永远不会完全稳定。因此,如何管理这种变化很重要。对大多数API来说,有充分的文档记录并逐步弃用API是可以接受的做法。