**RESTful API版本控制策略
做RESTful开放平台,一方面其API变动越少, 对API调用者越有利;另一方面,没有人可以预测未来,系统在发展的过程中,不可避免的需要添加新的资源,或者修改现有资源。因此,改动升级必不可少,但是,作为平台开发者,你必须有觉悟:一旦你的API开放出去,有人开始用了,你就不能只管自己Happy了,你对平台的任何改动都需要考虑对当前用户的影响。因此,做开放平台,你从第一个API的设计就需要开始API的版本控制策略问题,API的版本控制策略就像是开放平台和平台用户之间的长期协议,其设计的好坏将直接决定用户是否使用该平台,或者说用户在使用之后是否会因为某次版本升级直接弃用该平台。
版本控制策略模式
API的版本控制策略通常有3种模式:
第一种:The Knot:无版本,即平台的API永远只有一个版本,所有的用户都必须使用最新的API,任何API的修改都会影响到平台所有的用户。甚至平台的整个生态系统。
第二种:Point-to-Point:点对点,即平台的API版本自带版本号,用户根据自己的需求选择使用对应的API,需要使用新的API特性,用户必须自己升级。
第三种:Compatible Versioning:兼容性版本控制,和The Knot一样,平台只有一个版本,但是最新版本需要兼容以前版本的API行为。
三种策略对整个平台在升级API的开销对比如下:
以上信息来源于这篇文章:http://www.ebpml.org/blog2/index.php/2013/11/25/understanding-the-costs-of-versioning
作者以数学的方式详细的论述了这三种模式下,整个平台在升级API上的开销对比。
针对上面的论述,首先,API一定得有版本,否则升级对于用户来说将是噩梦。其次,要做到Compatible Versioning有现实的限制,毕竟API升级时,不可避免的会出现无法兼容老版本的状况,因此,版本控制需要结合第二种和第三种模式,即提供一个统一的兼容版本入口,同时对于不能兼容历史版本的API保留历史版本,支持用户能够调用到历史版本的API。另外,对历史版本的API支持一定要有时间和用户限制,即老版API支持到一定时间就删除,新用户必须使用新版API,否则一个API有10个版本会让平台的维护非常痛苦。
URI vs Request Parameter vs Media Type
在RESTful API领域,关于如何做版本控制,目前业界比较主流的有3种做法:
第一种:URI, 即在URI中直接标记使用的是哪个版本,无版本号URI默认使用最新版本。如下:
- http://xianlinbox/api/customers/1234
- http://xianlinbox/api/v3.0/customers/1234
好处:
直接可以在URI中直观的看到API版本,
可以直接在浏览器的查看各个版本API的结果
坏处:
版本号在URI中破坏了REST的HATEOAS(hypermedia as the engine of application state)规则。版本号和资源之间并无直接关系。
第二种:Request Parameter, 即在每个请求后添加一个version参数,表示请求的是哪个版本。如下:
- http://server:port/api/customer/123?version=2
这种做法其实就是URI方式的变种,好坏处也都一样。
第三种: Mdedia Type, 即在HTTP请求的header中使用Media Type标记该请求想获取的资源, 同样的可以不设置或设置通用的Media Type表示最新版本的API。
- ===>
- GET /customer/123 HTTP/1.1
- Accept: application/vnd.xianlinbox.customer-v3+json
- <===
- HTTP/1.1 200 OK
- Content-Type: application/vnd.xianlinbox.customer-v3+json
- {"customer":
- {"name":"Xianlinbox"}
- }
好处:
遵循了REST的设计风格,
坏处:
版本不直观,需要能设置header的client才能调用查看该API的效果。
**RESTful API版本控制策略的更多相关文章
- 细说RESTFul API之版本管理
目录 接口实现版本管理的意义 如何实现接口的版本管理 项目实战 接口实现版本管理的意义 API版本管理的重要性不言而喻,对于API的设计者和使用者而言,版本管理都有着非常重要的意义. 首先,对于API ...
- 让SpringMVC Restful API优雅地支持多版本
好久没有更新博客,难得有空,记录一下今天写的一个小工具,供有需要的朋友参考. 在移动APP开发中,多版本接口同时存在的情况经常发生,通常接口支持多版本,有以下两种方式: 1.通过不同路径区分不同版本 ...
- (转载) RESTful API 设计指南
作者: 阮一峰 日期: 2014年5月22日 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备......). 因此,必须有一种统一的机制 ...
- Node.js实现RESTful api,express or koa?
文章导读: 一.what's RESTful API 二.Express RESTful API 三.KOA RESTful API 四.express还是koa? 五.参考资料 一.what's R ...
- 基于轻量型Web服务器Raspkate的RESTful API的实现
在上一篇文章中,我们已经了解了Raspkate这一轻量型Web服务器,今天,我们再一起了解下如何基于Raspkate实现简单的RESTful API. 模块 首先让我们了解一下"模块&quo ...
- 使用python的Flask实现一个RESTful API服务器端[翻译]
最近这些年,REST已经成为web services和APIs的标准架构,很多APP的架构基本上是使用RESTful的形式了. 本文将会使用python的Flask框架轻松实现一个RESTful的服务 ...
- RESTful API 设计指南
转自:http://www.ruanyifeng.com/blog/2014/05/restful_api.html 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机. ...
- Restful API
http://www.ruanyifeng.com/blog/2011/09/restful 参考资料:-------以网络为基础的应用软件的架构设计. Restful API的设计与实践 字数218 ...
- 通过一组RESTful API暴露CQRS系统功能
命令和查询责任分离(CQRS)是由Greg Young提出的一种将系统的读(查询).写(命令)操作分离为两种独立子系统的架构模式.命令通常是异步执行的,并存储在一个事务型数据库中,而读操作则通常是最终 ...
随机推荐
- 简述afinal 框架的基本用法
本文只是对afinal做简单的描述,基本和git上给的文档一样,大神绕道! FinalDB模块本文为涉及到 FinalActivity模块,FinalHttp模块,FinalBitmap模块 代码体 ...
- iOS学习之C语言结构体
结构体:用来存放相同类型数据或者不同类型数据的自定义类型. 结构体定义(声明) struct 结构体名 { 成员变量1; 成员变量2; ... }; typedef 现有类型 新的类 ...
- 关于Swift中实现Lazy initialize的方式
在oc中我们通过 -(CardMatchingGame *)game { if(!_game) _game=[[CardMatchingGame alloc] initWithCardCount:[s ...
- Sharepoint 2010 RBS 的安装和配置
基本上按照微软官方的配置方法配置就行了. 给下地址:微软官方 涂大神 找RBS的安装文件也是个问题,微软的链接好像失效了.我使用的是RBS下载.这里也有. 我的环境是数据库两台故障群集转移,微 ...
- 56.ISE综合,在chipscope信号列表看不到
代码写好后,进行逻辑综合,在chipscope上添加被触发的信号时,发现有些在信号列表里看不到,这是因为这些信号没有参与到逻辑电路设计中,产生不想关的电路,综合器会默认优化资源. 还有一种情况是,对于 ...
- Linux 删除mysql数据库失败的解决方法
使用命令:drop database xxx:删除本数据库时却删除失败,系统提示出现了错误,错误代码为: ERROR 1010 (HY000): Error dropping database(can ...
- 基础语法 swift
强类型语言:每句代码可以不用分号分隔:大小写敏感: 变量声明: var a = 0 常量声明 let b = 3.14 常量不能+变量?a+b 类型标注 var s :String 打印 pringl ...
- 查mysql字段中的数字记录
select * from a where nameregexp '^[0-9]+$' ;
- 四则运算(2)之软件单元测试:Right-BICEP
一.Right-BICEP主要测试以下几方面的问题: Right-结果是否正确? B-是否所有的边界条件都是正确的? I-能查一下反向关联吗? C-能用其他手段交叉检查一下结果吗? E-你是否可以强制 ...
- 关于ASCII、GB231、GBK、UTF-8/UTF8、ANSI、unicode的学习笔记
继续上次的学习内容,写一些自己学习的笔记吧!总是觉得没有笔记的学习总是不那么踏实,我承认自己是个记忆力很差的人,特别羡慕那些可以把自己学过的东西记得很牢靠的人.哎!可惜我不是,那只能做出来点东西,就算 ...