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/in... 作者以数学的方式详细的论述了这三种模式下,整个平台在升级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的效果。
原文:http://itindex.net/detail/470...版本控制
RESTful API版本控制策略相关推荐
- 让SpringMVC Restful API优雅地支持多版本
好久没有更新博客,难得有空,记录一下今天写的一个小工具,供有需要的朋友参考. 在移动APP开发中,多版本接口同时存在的情况经常发生,通常接口支持多版本,有以下两种方式: 1.通过不同路径区分不同版本 ...
- Docker——基于HubServing部署全套PaddleOCR Restful API服务(CPU版本)
说明 1.同时部署ocr_det.ocr_cls.ocr_rec.ocr_system 2.基于https://gitee.com/paddlepaddle/PaddleOCR/blob/v2.0.0 ...
- PaddleOCR——Docker环境下基于HubServing模式部署Restful API服务(CPU版本)
Docker环境下基于HubServing模式部署Restful API服务(CPU版本) 在日常项目应用中,相信大家一般都会希望能通过Docker技术,把PaddleOCR服务打包成一个镜像,以便在 ...
- 一文讲解Elasticsearch java restful api 跨版本兼容解决方案
需求来源 之前的文章elasticsearch&kibana从6.0升级到7.9完整过程记录已经已经介绍了该需求的来源,也已经将elasticsearch的server端从6.0.0升级到了7 ...
- java鉴权_一个开箱即用的高效认证鉴权框架,专注于restful api的认证鉴权动态保护...
作者:tomsun28 来源:SegmentFault 思否 写在开头 看了看这个专栏的最近一篇文章已经是两年前了,时间过得好快.应该是出学校后时间就很快了.两年前因为用shiro后,自己就按着想法开 ...
- Yii2.0 RESTful API 之版本控制
Yii2.0 RESTful API 之版本控制 之前我写过两篇关于 Yii2.0 RESTful API 如何搭建,以及 认证 等处理,但是没有涉及到版本管理,今天就来谈谈版本管理如何实现. 索性就 ...
- 我是如何根据豆瓣api来理解Restful API设计的
1.什么是REST REST全称是Representational State Transfer,表述状态转移的意思.它是在Roy Fielding博士论文首次提出.REST本身没有创造新的技术.组件 ...
- RESTful API 设计最佳实践
2019独角兽企业重金招聘Python工程师标准>>> 背景 目前互联网上充斥着大量的关于RESTful API(为方便,下文中"RESTful API "简写为 ...
- 用python写通用restful api service(一)
一直在用node.js做后端,要逐步涉猎大数据范围,注定绕不过python,因此决定把一些成熟的东西用python来重写,一是开拓思路.通过比较来深入学习python:二是有目标,有动力,希望能持之以 ...
最新文章
- JavaScript基础系列---闭包及其应用
- 凯撒密码C语言去掉空格字符,凯撒密码的问题C语言
- 【Binder 机制】进程通信 | 用户空间与内核空间 | MMU 与虚拟内存地址
- python合法标识符_python_判断标识符的合法性
- mysql 备库,高性能MySQL:主库、分发主库以及备库
- 是什么影响了数据库索引选型?
- 提升SQL Server速度 整理索引碎片
- git查看某次提交的内容
- de4dot构建过程
- DWG转PDF在线转换怎么转?这个方法线上线下都能用
- dep指定版本 go_Go语言包管理工具dep的安装与使用
- wireshark绿色便携版 v3.4.2.0
- linux中pingpong测试程序的解读
- sql server 2012 KB2716442安装错误解决方案(错误代码 0x84B20001)
- 我对于创业公司的看法
- Java设计模式第一章(软件设计原则)(学习笔记)
- 读作工业4.0,唱作工业互联网,写作中国制造2025
- 雄关漫道真如铁,而今迈步从头越 | 挥别2022,再战2023!
- 《Real-Time Rendering 4th Edition》全文翻译 - 第4章 变换(下)4.5 ~ 4.7
- uni-app蓝牙设备连接以及设备的传输,CRC16,ios蓝牙和安卓蓝牙获取数据不一致处理方案
热门文章
- Keil uvision 4 MDK 安装教程附免费安装包资源
- javaee实验报告心得_准大四学生七月青软实训总结
- 计算机视觉与深度学习 | 基于DNN神经网络实现人的年龄及性别预测(代码类)
- notepad++是什么?用notepad++来编辑c语言代码
- iphone计算机快捷键,苹果电脑快捷键大全,最常用的都在这里了
- JVM实战与原理---内存回收策略
- html表格的表头怎么合并单元格,使用tableGrob合并表头单元格
- 【机器学习】使用奇异值分解(SVD)构建推荐系统
- 【机器学习】如果你不了解机器学习的简史,请看这篇文章
- 【数据分析】数据分析基础:SQL重要知识点梳理!