RESTful API版本控制策略

标签: restful api 版本控制 | 发表时间:2013-12-15 19:51 | 作者:
出处:http://www.iteye.com
做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的效果。

已有 0 人发表留言,猛击->> 这里<<-参与讨论


ITeye推荐



相关 [restful api 版本控制] 推荐:

RESTful API版本控制策略

- - ITeye博客
做RESTful开放平台,一方面其API变动越少, 对API调用者越有利;另一方面,没有人可以预测未来,系统在发展的过程中,不可避免的需要添加新的资源,或者修改现有资源. 因此,改动升级必不可少,但是,作为平台开发者,你必须有觉悟:一旦你的API开放出去,有人开始用了,你就不能只管自己Happy了,你对平台的任何改动都需要考虑对当前用户的影响.

RESTful API 设计指南

- - 阮一峰的网络日志
网络应用程序,分为前端和后端两个部分. 当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备......). 因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信. 这导致API构架的流行,甚至出现 "API First"的设计思想. RESTful API是目前比较成熟的一套互联网应用程序的API设计理论.

RESTful API 设计最佳实践

- - 文章 – 伯乐在线
项目资源的URL应该如何设计. 用哪种HTTP方法来创建一个新的资源. 实现分页和版本控制的最好方法是什么. 因为有太多的疑问,设计RESTful API变得很棘手. 在这篇文章中,我们来看一下RESTful API设计,并给出一个最佳实践方案. 资源集合用一个URL,具体某个资源用一个URL:. #资源集合的URL /employees/56.

【翻译】优秀的RESTful API的设计原则

- - 行业应用 - ITeye博客
原文地址: http://codeplanet.io/principles-good-restful-api-design/. 原文作者:Thomas Hunter Ii. 第一次翻译,若有不对的地方,敬请谅解,若转载请注明本文地址. 定义(Definitions). 数据的设计与抽象化(Data Design and Abstraction).

我所认为的RESTful API最佳实践

- - ScienJus's Blog
在开始本文之前,我想先说这么一句:RESTful 真的很好,但它只是一种软件架构风格,过度纠结如何遵守规范只是徒增烦恼,也违背了使用它的初衷. 就像 Elasticsearch 的 API 会在 GET 请求中直接传 JSON,但这是它的业务需要,因为普通的 Query Param 根本无法构造如此复杂的查询 DSL.

分析 RESTful API 安全性及如何采取保护措施

- - V2EX - 技术
本文中讨论了 API 安全性和采用安全措施的重要性,如身份验证,API 密钥,访问控制和输入验证. API 设计的第一步是撰写接口文档. 根据 TechTarget (海外 IT 专业媒体)的定义,RESTful API 是一个应用程序接口,它使用 HTTP 请求来获取 GET,PUT,POST 和 DELETE 等数据.

Apache Hadoop 1.0.0支持Kerberos验证,支持Apache HBase,提供针对HDFS的RESTful API

- - InfoQ中文站
海量数据框架Apache Hadoop怀胎六年终于瓜熟蒂落发布1.0.0版本. 本次发布的核心特性包括支持Kerberos身份验证,支持Apache HBase,以及针对HDFS的RESTful API. InfoQ就此次发布请Apache Hadoop项目的VP——Arun Murthy回答了几个问题.

每天用SpringBoot,还不懂RESTful API返回统一数据格式是怎么实现的?

- - SegmentFault 最新的文章
关于 Spring 的全局处理,我有两方面要说:. 为了将两个问题说明清楚,将分两个章节分别说明,本章主要说第一点. 有童鞋说,我们项目都做了这种处理,就是在每个 API 都单独工具类将返回值进行封装,但这种不够优雅;我想写最少的代码完成这件事,也许有童鞋说,加几个注解就解决问题了,说的没错, 但这篇文章主要是为了说明为什么加了几个注解就解决问题了,目的是希望大家知其所以然.

理解RESTful架构

- InterMa - 阮一峰的网络日志
越来越多的人开始意识到,网站即软件,而且是一种新型的软件. 这种"互联网软件"采用客户端/服务器模式,建立在分布式体系上,通过互联网通信,具有高延时(high latency)、高并发等特点. 网站开发,完全可以采用软件开发的模式. 但是传统上,软件和网络是两个不同的领域,很少有交集;软件开发主要针对单机环境,网络则主要研究系统之间的通信.