**RESTful API版本控制策略

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

做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默认使用最新版本。如下: 

Java代码   收藏代码
  1. http://xianlinbox/api/customers/1234  
  2. http://xianlinbox/api/v3.0/customers/1234  

好处: 
直接可以在URI中直观的看到API版本, 
可以直接在浏览器的查看各个版本API的结果 
坏处: 
版本号在URI中破坏了REST的HATEOAS(hypermedia as the engine of application state)规则。版本号和资源之间并无直接关系。 

第二种:Request Parameter, 即在每个请求后添加一个version参数,表示请求的是哪个版本。如下: 

Java代码   收藏代码
  1. http://server:port/api/customer/123?version=2  


这种做法其实就是URI方式的变种,好坏处也都一样。 

第三种: Mdedia Type, 即在HTTP请求的header中使用Media Type标记该请求想获取的资源, 同样的可以不设置或设置通用的Media Type表示最新版本的API。 

Java代码   收藏代码
  1. ===>  
  2. GET /customer/123 HTTP/1.1  
  3. Accept: application/vnd.xianlinbox.customer-v3+json  
  4.   
  5. <===  
  6. HTTP/1.1 200 OK  
  7. Content-Type: application/vnd.xianlinbox.customer-v3+json  
  8.   
  9. {"customer":  
  10.   {"name":"Xianlinbox"}  
  11. }  

好处: 
遵循了REST的设计风格, 
坏处: 
版本不直观,需要能设置header的client才能调用查看该API的效果。

如何联系我:【万里虎】www.bravetiger.cn 【QQ】3396726884 (咨询问题100元起,帮助解决问题500元起) 【博客】http://www.cnblogs.com/kenshinobiy/
目录
相关文章
|
8天前
|
IDE Java API
使用Java Web技术构建RESTful API的实践指南
使用Java Web技术构建RESTful API的实践指南
|
24天前
|
Web App开发 JavaScript NoSQL
深入浅出:构建基于Node.js的RESTful API
在当今快速发展的互联网时代,RESTful API已成为前后端分离架构中不可或缺的一部分。本文旨在为初学者和中级开发人员提供一个清晰、简洁的指南,详细介绍如何使用Node.js构建一个高效、可维护的RESTful API。通过结合实际案例,本文将从API设计理念出发,深入讲解如何利用Express框架及MongoDB数据库实现API的增删改查功能,同时探讨如何通过JWT进行安全认证,确保数据传输的安全性。此外,文章还将简要介绍如何使用Swagger生成API文档,使得API的测试和维护更加便捷。无论你是希望提升现有项目的API设计,还是想从零开始构建一个新项目,本文都将为你提供一条清晰的道路
|
1天前
|
缓存 中间件 API
|
2天前
|
API 开发者 UED
深入理解RESTful API设计原则
【2月更文挑战第9天】 传统的RESTful API设计原则在实际开发中并不是一成不变的,随着技术的发展和应用场景的变化,我们需要不断深入理解RESTful API的设计原则,并结合具体情况进行灵活应用,以更好地满足现代应用的需求。
12 4
|
5天前
|
API 网络架构
解释 RESTful API,以及如何使用它构建 web 应用程序。
解释 RESTful API,以及如何使用它构建 web 应用程序。
12 0
|
16天前
|
缓存 Rust 安全
Rust中的RESTful API构建:实践与探索
本文详细阐述了在Rust编程语言中如何构建RESTful API的过程。我们将通过实际示例,介绍Rust的生态系统中用于构建API的流行库和框架,包括Actix-Web、Rocket和Gotham。此外,我们还将讨论RESTful设计原则、API安全性、性能优化等方面的内容,帮助读者在Rust中高效、安全地构建RESTful API。
|
22天前
|
存储 缓存 API
深入理解与实践RESTful API设计
在数字化时代,RESTful API已成为应用程序之间交互的重要桥梁。本文旨在提供一个全面的指南,从RESTful API的基本概念入手,深入探讨其设计原则、最佳实践以及常见的挑战。不同于一般的技术文章仅停留在表面的介绍,我们将结合实际案例,逐步分析如何设计一个既符合REST原则又能满足现代应用需求的API。通过本文,读者不仅能够掌握RESTful API的理论知识,更能学会如何在实际项目中灵活应用,从而提升整个系统的可扩展性和维护性。
|
24天前
|
缓存 安全 API
深入理解Web开发中的RESTful API设计
在当今快速演进的技术世界中,RESTful API已成为构建现代Web应用不可或缺的一部分。它不仅促进了前后端的分离发展,还为不同平台间的数据交换提供了一种高效、标准化的方式。本文旨在深入探讨RESTful API的设计原则和最佳实践,通过具体示例说明如何设计易于维护、可扩展和安全的API。我们将从REST的基本概念出发,逐步深入到资源命名、HTTP方法的恰当使用、状态码的选择、以及安全性考虑等方面,为读者提供一个全面而深入的视角,帮助大家更好地理解和运用RESTful API。
|
26天前
|
前端开发 Java API
构建强大的RESTful API:@RestController与@Controller的对比与应用
构建强大的RESTful API:@RestController与@Controller的对比与应用
23 0
|
27天前
|
NoSQL JavaScript 前端开发
深入浅出:使用Node.js和MongoDB构建RESTful API
在当今的软件开发领域,构建高效、可扩展的Web服务已成为开发者的重要任务之一。本文将引导读者通过现代JavaScript环境——Node.js,搭配流行的NoSQL数据库MongoDB,一步步构建一个RESTful API。不同于常规的摘要,我们将采用故事化的方式,通过一个虚构的应用“BookFinder”的开发旅程,带领读者理解API设计、数据库交互及安全性考量等关键知识点。无论你是前端工程师希望深化后端知识,还是后端新手寻求实践机会,本文都将提供你所需的指南和启示。

相关产品

  • 云迁移中心