做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的效果。
- 大小: 105.8 KB
- 大小: 107.1 KB
- 大小: 139.8 KB
- 大小: 225.9 KB
分享到:
相关推荐
RESTFUL API设置最佳实 PDF
Versionist开箱即用地支持三种版本控制策略:通过HTTP标头指定版本通过在路径之前添加版本标记来指定版本versionist一个用于对基于Rails的RESTful API进行版本控制的插件。 Versionist支持三种开箱即用的版本控制...
RESTful 原则提供了 HTTP methods 映射作为策略来处理 CRUD actions,如下: GET /tickets - 获取 tickets 列表 GET /tickets/12 - 获取一个单独的 ticket POST /tickets - 创建一个新的 ticket PUT /tickets/12 - ...
第一个宁静的API,用于控制所有防火墙品牌。 使用宁静的API调用配置任何防火墙,而无需手动进行任何规则配置。 将所有防火墙集中到一个API中。 多平台 帕洛阿尔托 杜松 思科公司 福汀 检查站 PfSense AWS ...
您喜欢路径版本控制策略吗? Dart允许您执行此操作。 是否想通过扩展策略使用内容类型? Dart(Darter)也允许您执行此操作。为什么要使用Darter? 因为您想要灵活地实现您的API。 我们相信,在构建新应用程序时,...
API版本控制 限速 响应变压器和格式化器 错误和异常处理 内部要求 API蓝图文档 文献资料 请参考我们广泛的以获取更多信息。 API样板 如果您想从头开始一个新项目,请考虑使用 ,它基于dingo-api软件包,并增加了许多...
同样,每个交互都将被保存和版本控制。 设置策略-您可以定义负载平衡策略并为每个目标设置权重。 这适用于加权轮询和其他类似策略。 启动负载平衡服务-您可以创建一个配置文件,该配置文件随后用于启动负载平衡...
锚固引擎 有关Anchore Engine,Anchore CLI和其他Anchore软件的最新...通过与RESTful API集成而集成到现有容器监视和控制框架中的组件。 Anchore Engine还是的OSS基础,它添加了图形UI(提供策略管理,用户管理,摘要
MyApi模板 :high_voltage: 通过实时重新启动您的api即时观看更改 :chart_increasing: 使用可高度扩展,从而更轻松地访问数据库 :smiling_face_with_sunglasses: 带有OpenAPI描述您的RESTful API :sparkles: KISS原则...
AuthzForce服务器(社区版) AuthzForce Server为定义的基于属性的访问控制(ABAC)的策略管理点(PAP)和策略决策点(PDP)提供了多租户RESTful API。 该项目是一部分。 有关更多信息,请检查FIWARE目录条目中的“ ...
使用API控制器使用.NET Core构建RESTful API 使用Hooks创建强类型的,基于交互的,基于函数的React组件使用可重用的React组件高效地构建表单使用Redux和React Context API执行客户端状态管理具有ASP.NET身份和...
1. 前后端分离技术:前端采用HTML、CSS和JavaScript等Web前端技术进行页面布局和交互设计,后端负责处理业务逻辑和数据存储,前后端通过RESTful API进行数据交互,提高了系统的灵活性和可扩展性。 2. 数据库设计与...
同时,系统采用了前后端分离的开发模式,前端使用现代化的UI框架,后端提供RESTful API接口,保证了系统的可扩展性和可维护性。 除了基本的业务功能外,该系统还注重数据的安全性和隐私保护。通过数据加密、权限...
32. 跨语言:系统提供语言无关的 RESTFUL API 服务,第三方任意语言可据此对接Task Manage; 33. 国际化:后管系统支持国际化设置,提供中文、英文两种可选语言,默认为中文; 34. 容器化:提供官方docker镜像,并...
Nacos 还提供包括配置版本跟踪、金丝雀发布、回滚配置以及客户进程配置更新状态跟踪在内的一系列开箱即用的配置管理特性,帮助您更安全地管理配置变更和控制配置变更的风险。 动态 DNS 服务 动态 DNS 服务支持...
如何保障高并发系统的稳定运行,如采用流量控制、依赖管理、服务分级、开关等策略,以及介绍如何设计高并发系统。 如何优化应用的性能,包括前端优化、Java程序优化、数据库查询优化等。 如何进行Java应用故障...
30、跨语言:调度中心与执行器提供语言无关的 RESTful API 服务,第三方任意语言可据此对接调度中心或者实现执行器。除此之外,还提供了 “多任务模式”和“httpJobHandler”等其他跨语言方案; 31、国际化:调度...
OpenIDM使您能够整合多个身份源,以进行基于策略和基于工作流的管理。 OpenIDM可以使用,转换数据并将其提供给外部源,以便您可以控制用户,设备和其他对象的身份。 OpenIDM提供了现代的UI体验,使您无需编写任何...
在Flex程序之间使用RESTful通信 18.3. 配置和连接RemoteObject 18.4节. 使用AMFPHP 1.9中的FlexRemoting 18.5节. 使用IExternalizable接口自定义序列化 18.6节. 跟踪多个同时发生的服务调用的结果 18.7节. 使用发布...
平台服务层的调用是通过RESTAPI进行的,由于REST的特点,通过在URI中添加资源路径以及版本信息,很方便地能够实现平台的平滑升级以及数据兼容性问题。 平台服务层实现的都是共通的服务,服务之间是独立的,而且...