如何对API进行版本化?

随着公司业务规模的不断扩大和业务深度的不断扩展,是必会导致技术团队API的不断变化,当这一变化会破坏现有客服端集成时,如何管理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是可以接受的做法。

linux sudoers 用户权限配置
什么是 SSL证书?SSL证书详解
标签:

发表我的评论

电子邮件地址不会被公开。 必填项已用*标注

ajax-loader