报名参加CloudWeGo黑客松,奖金直推双丰收! 了解详情
写点什么

如何版本化你的 API?

  • 2017-09-11
  • 本文字数:1917 字

    阅读完需:约 6 分钟

如何版本化 API 需要考虑各种实际业务场景,但是一个完备的 API 应该是:

  • 和客户端交互的约定。API 需要确保稳定性,预先定义各种可能返回状态,包括各种异常。客户端无需考虑约定之外的情况。
  • 向下兼容。在 API 没有变化的时候,API 实现的更新和升级,都应该确保原有客户端请求不出现问题。
  • RESTful。API 设计应该能够遵照 RESTful 风格,通过 URI 来表示资源,通过 HTTP GET、POST、PUT、DELETE 等方法表示操作行为。

为了满足上述约定,版本化 API 不失为一种保持兼容性的好方法。版本化 API 的通常方式有:

URI 中设置版本

这种方式通常在 URI 中增加一段用于标识版本,例如/v1/v2等。例如:

复制代码
curl https://example.com/api/v2/lists/3

这种方式的优势在于版本信息很容易明显的看出来,可以通过浏览器直接访问。

HTTP 头中设置版本

这种方式的版本信息会放在 HTTP 的请求头中,通常会利用Accept字段,或者自定义一个字段。例如:

复制代码
curl https://example.com/api/lists/3 \
-H 'Accept: application/vnd.example.v2+json'

这种方式的好处是当版本升级时,URI 保持不变,并且仅用于表示资源定位。

没有版本

版本化的目的是为了标识 API 的变化,如果 API 不会变化,或者每次都会重新扩展新的 API,这种情况下,就可以标识版本信息。例如:

curl https://example.com/api/lists/3一种折中方案

前面提到了三种版本化 API 的方式,通常情况下需要针对自己业务的特殊性来挑选其中的一种方式。但是,在实际应用场景中,情况会更加复杂,API 的升级通常有两种情况:

  1. 大版本更新,例如字段类型变更、数据对象变更等。这种情况下无法满足对客户端的向下兼容,因此需要修改版本号。
  2. 小版本更新,例如增加可选参数、增加返回字段等。这种情况对于新客户端可以增加功能,对于老客户端仍然可以保持原有功能,可以不修改版本号。

因此,本文提出的折中方案是基于 URI 中的大版本号和 HTTP 头中的小版本号整合的方式。下面通过一个简单的示例来解释。

用户管理平台

一个常用的用户管理平台,提供以下 API,通过用户 ID 获取用户信息:

复制代码
curl https://example.com/api/v1/user/1
...
{
"id": 1,
"name": "test",
"email": "test@example.com"
}

考虑以下两种变动情况:一种是用户 id 从数字变成了字符串,另一种是新增一个用户头像的值。

前者修改因为数据类型的变化,会导致客户端解析出现问题。因此这样的修改已经破坏了向下兼容性,此时就需要修改 API 的版本号。例如:

复制代码
curl https://example.com/api/v2/user/1
...
{
"id": "1",
"name": "test",
"email": "test@example.com"
}

第二种情况,对于旧客户端来说,只是增加了不使用的字段,通常的 JSON 格式解析库都可以忽略这些不使用的字段。对于新客户端则可以读取新的字段。例如:

复制代码
curl https://example.com/api/v2/user/1
...
{
"id": "1",
"name": "test",
"email": "test@example.com",
"avatar": "http://example.com/1.jpg"
}

这种情况下,基本可以做到向下兼容,因此可以算是“小版本升级”。针对小版本升级,可以将小版本号放到 HTTP 头中。例如:

复制代码
curl https://example.com/api/v2/user/1 \
-H 'API-VERSION: 20170801'
...
{
"id": "1",
"name": "test",
"email": "test@example.com",
"avatar": "http://example.com/1.jpg"
}

后端路由

由于混合版本化的方式同时涉及到 URI 和 HTTP 头字段,前端代理(例如 HAProxy、nginx)可以通过这些特定版本号字段将请求代理到对应的后端应用。

例如,前端使用 HAProxy 进行多版本分发,可以针对 URI 和 HTTP 头定制 acl,然后再对这些 acl 进行组合,设置不同的 backend。

复制代码
acl is_v1 path_beg /api/v1
acl is_v2 path_beg /api/v2
acl is_version_1 hdr(API-VERSION) 20170801
acl is_version_2 hdr(API-VERSION) 20170701
use_backend old_server if is_v1 is_version_1
use_backend new_server if is_v2 is_version_2
backend old_server
...
backend new_server
...

这样可以将 API 版本化规则应用到不同的后端,以保证向下兼容性。

总结

基于本文版本化 API 规则,将“大版本”应用在 URI 上,将“小版本”应用在 HTTP 头字段上。通常来说,如果 API 升级之后破坏了向下兼容性,就应该升级“大版本”号;如果 API 升级可以向下兼容,可以升级“小版本”号。

版本化 API 有很多不同的设计方式,本文仅是其中一种。实际应用时,还是要根据业务场景进行选择,包括 API 版本升级频率,API 稳定性等。通过 HAProxy、nginx 等代理服务,可以在确保向下兼容的情况下,由业务方决定老版本 API 的保留时间。


感谢郭蕾对本文的审校。

给InfoQ 中文站投稿或者参与内容翻译工作,请邮件至 editors@cn.infoq.com 。也欢迎大家通过新浪微博( @InfoQ @丁晓昀),微信(微信号: InfoQChina )关注我们。

2017-09-11 19:008413

评论

发布
暂无评论
发现更多内容

一步一步教你如何在Centos7中配置Kafka运行时环境

happlyfox

28天写作 3月日更

滚雪球学 Python 之闭包操作,本系列第 8 篇文章

梦想橡皮擦

28天写作 3月日更

植树节,种个二叉树吧?

悟空聊架构

数据结构 算法 二叉树

一起来学习LiteOS中断模块的源代码

华为云开发者联盟

代码 华为云 LiteOS 中断 中断控制器

《精通比特币》学习笔记(第八章)

棉花糖

区块链 学习 3月日更

物联网常用协议:MQTT、CoAP、LwM2M、HTTP、LoRaWAN和NB-IoT

不脱发的程序猿

物联网 通信协议 28天写作 3月日更 物联网常用协议

你以为在做的是微服务?不!你只是做了个比单体还糟糕的分布式单体!

程序猿DD

微服务

2月大事件:度目CM-Mini智能面板机全新发布,飞桨PaddleGAN“复活”李焕英

百度大脑

百度 百度大脑

数字孪生技术如何实现复制世界?关键的关键是…

华为云开发者联盟

数据中心 数字孪生 节能 仿真 数据中心网图服务

这是看脸的时代吗——晕轮效应

Justin

心理学 28天写作 游戏设计

硬核!一文学完Flink流计算常用算子(Flink算子大全)

五分钟学大数据

大数据 flink 28天写作 3月日更

对标阿里P9Java架构师面试题,已助我拿下字节、蚂蚁、滴滴三家Offer

Java架构追梦

Java 阿里巴巴 架构 面试 滴滴

“种”下黑科技,守护每株绿,“植”了!

华为云开发者联盟

华为 AI IoT modelarts 森林

【LeetCode】验证二叉树的前序序列化Java题解

Albert

算法 LeetCode 28天写作 3月日更

寻找被遗忘的勇气(十二)

Changing Lin

3月日更

安卓系统开发架构!5214页PDF的进阶架构师学习笔记,成功入职腾讯

欢喜学安卓

android 程序员 面试 移动开发

ECMAScript 2016(ES7)新特性简介

程序那些事

JavaScript ecmascript ES6 程序那些事 es7

真·“拜师学艺”?2021中科院开源之夏,开源大牛1V1&万元奖金只等你来!

京东科技开发者

开源 开源社区

“新作者 新入驻 新征程”第一季获奖名单

InfoQ写作社区官方

热门活动

细粒度授权在安全领域的重要性

龙归科技

安全 iam 细粒度 ABAC PBAC

翻译:《实用的Python编程》05_01_Dicts_revisited

codists

Python

关于广东欢太科技可不可信?那是你还不了解

Geek_4a453c

企业 欢太 欢太科技

聊聊什么是CommonJs和Es Module及它们的区别

蛙人

大前端 js ES6

区块链应用解决方案赋能到农产品溯源上究竟能解决什么问题?

源中瑞-龙先生

力扣(LeetCode)刷题,简单题(第27期)

不脱发的程序猿

面试 LeetCode 28天写作 算法面经 3月日更

与前端训练营的日子 -- Week19

SamGo

学习

如何成为一名架构师?

xcbeyond

程序人生 方法论 架构师 成长与思考 3月日更

《未来世界的幸存者》读书笔记

SilentMacUser

极客时间 互联网 技术学习 阅读 阮一峰

带你了解VXLAN网络中报文的转发机制

华为云开发者联盟

网络 网关 VXLAN 报文 分布式网关

华云大咖说 | 华云数据与瀚高软件携手共建国产云生态 助力政企用户安全可靠发展

华云数据

安卓应用程序开发理论!免费Android高级工程师学习资源,附面试题答案

欢喜学安卓

android 程序员 面试 移动开发

如何版本化你的API?_架构_金灵杰_InfoQ精选文章