如何版本化你的API?
来源:互联网 发布:mongodb删除数据 编辑:程序博客网 时间:2024/06/02 07:29
如何版本化你的API?
转自:InfoQ, http://www.infoq.com/cn/news/2017/09/How-versioning-API
如何版本化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的升级通常有两种情况:
- 大版本更新,例如字段类型变更、数据对象变更等。这种情况下无法满足对客户端的向下兼容,因此需要修改版本号。
- 小版本更新,例如增加可选参数、增加返回字段等。这种情况对于新客户端可以增加功能,对于老客户端仍然可以保持原有功能,可以不修改版本号。
因此,本文提出的折中方案是基于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/v1acl is_v2 path_beg /api/v2acl is_version_1 hdr(API-VERSION) 20170801acl is_version_2 hdr(API-VERSION) 20170701use_backend old_server if is_v1 is_version_1use_backend new_server if is_v2 is_version_2backend old_server...backend new_server...
这样可以将API版本化规则应用到不同的后端,以保证向下兼容性。
总结
基于本文版本化API规则,将“大版本”应用在URI上,将“小版本”应用在HTTP头字段上。通常来说,如果API升级之后破坏了向下兼容性,就应该升级“大版本”号;如果API升级可以向下兼容,可以升级“小版本”号。
版本化API有很多不同的设计方式,本文仅是其中一种。实际应用时,还是要根据业务场景进行选择,包括API版本升级频率,API稳定性等。通过HAProxy、nginx等代理服务,可以在确保向下兼容的情况下,由业务方决定老版本API的保留时间。
- 如何版本化你的API?
- 如何保护你的API
- SVN绝配,版本库先考你服务器端版本与客户端的版本如何匹配!巧合吗
- 如何查看你的浏览器的Flash版本
- Web API 版本化的介绍
- <Web>地理定位API如何确定你的位置
- 手把手教你如何搭建本地的 Java API 文档
- 如何快速选择适合你的NiceLabel版本
- Linux命令 ----如何查看你的ubuntu 版本
- 教你如何自己制作IP地址查询的API,摆脱第三方API---(一)
- 教你如何自己制作IP地址查询的API,摆脱第三方API---(二)
- android O api 已发布最终版本,让你的应用做好准备
- WSAStartup函数如何确定Sockets API版本
- APP API如何维护多个版本
- 如何创建google api cient id & api key 图文版本
- Android低版本上如何调用高版本API
- API版本的TrimNull函数
- [iOS]关于如何在项目中同时适配低版本和高版本的API的一点小见解
- 换个角度看回归——极大似然估计
- android 自定义键盘控件_身份证号码输入
- 装饰者设计模式
- Android监听用户打开系统相机进行录像行为
- Java笔记之形参个数可变的方法
- 如何版本化你的API?
- Arduino使用HC05蓝牙模块与手机连接
- 比较重量(网易笔试题)
- cmd中netstat 命令详解(四)
- 2017青岛网络赛1008 Chinese Zodiac
- woocommerce中将可变商品的下拉选项框改为淘宝类似的款式点选
- Linux 内核list_head 学习(一)
- Windows批处理.bat检测是否安装某些软件
- 线性神经网络在Matlab中实现