版本控制是计算机软件行业人士使用的术语。但进化是我们所有人都要经历的事情,它适用于这个世界上的每个对象。

在计算机软件行业,可以看到每3至4年,每台计算机软件都会附带不同的发行版/版本,以满足当前/现代的要求。
Microsoft Windows版本历史记录
版本控制是创建和管理软件产品的多个版本的实践,消费者可以根据自己的需求决定使用哪个版本,API的管理也是如此。

API的创建始终始于使应用程序与内部/外部应用程序开发人员集成的想法。就像任何其他传统软件产品一样,它总是从小规模开始,并且会随着时间而发展。让我们看下面的简单用例,以更好地理解它。

例如,我们可能希望使内部/外部应用程序开发人员能够访问客户信息,并且可能开始创建API以提供所需的功能。

作为第一个版本,您可以为API提供仅对客户信息的读取权限。后来,随着对应用程序需求的增加,您的应用程序开发人员可能会请求对客户信息的“写入/更新”访问权限。作为API创建者/开发者,您可以决定是否:

  1. 提供具有对客户信息的写入/更新访问权限的同一API的新版本;
  2. 完全提供单独的API,以提供对客户信息的写入/更新访问权限;

API的通用设计原则是使用第一种方法-从应用程序开发人员的角度来看,为我们提供相同功能的API的新版本,以及我们处理同一实体(客户)时的附加功能。这将导致具有相同API的2个版本:
• CustomerInfo v1.0-提供对客户信息的只读访问;
• CustomerInfo v2.0 —提供对客户信息的读/写/更新访问;
在这里插入图片描述
通过API的版本控制,CustomerInfo API的使用者可以根据需要决定使用哪个版本。

当我们想支持同一个API的多个版本时,作为API创建者/设计者,我们需要考虑以下02个主要设计决策:
• 指定API版本信息的格式是什么;
• 消费者将如何指定所选API的API版本;

选择用于指定版本信息的格式时,可以选择以下02种常见做法:

使用发布/构建日期-这允许使用发布/构建日期来唯一标识每个版本。
示例—版本=“ 20200808” | 版本=“ 20190102”
在这里插入图片描述

使用major.minor数字 -这些数字用于指定同一API的不同版本,并且该数字可以包含1或2或3位数字作为版本号的一部分。一些API开发人员使用“ v”前缀来表示它是版本号。
示例— version =“ 1” | 版本=“ v1” | 版本=“ 1.1” | 版本=“ v1.1” | 版本=“ 1.1.1” | 版本=“ v1.1.1”在这里插入图片描述

在决定使用者如何指定版本信息时,可以从以下03种常见做法中进行选择:
HTTP标头-自定义HTTP标头将用于传递API版本信息
示例— x-customerinfoapi-version:2.1
在这里插入图片描述

查询参数-API版本信息将作为查询参数传递
示例-/customerinfo?version=2.1
在这里插入图片描述

URL -API版本信息将合并到URL本身
示例-/ v2 / customerinfo
在这里插入图片描述

作为API的创建者/开发者,我们还可以结合上面的一些方法,并提供用于提供API版本信息的混合方法。例如,我们可以使用URL方法来指定主要版本,而可以使用HTTP标头方法来指定API的次要版本。
如您所见,API版本控制是API设计/开发中的关键功能,并且作为API提供程序,使消费者能够在不同的API版本之间进行选择是关键的业务差异。

翻译:Eolinker
原文地址:https://dzone.com/articles/api-versioning-2

Logo

权威|前沿|技术|干货|国内首个API全生命周期开发者社区

更多推荐