接口实现版本管理的意义和最佳方法
2019,11,18 博客

API版本管理的重要性不言而喻,对于API的设计者和使用者而言,版本管理都有着非常重要的意义。下面会从WEB API 版本管理的角度提供几种常见办法:

首先,对于API的设计和实现者而言,需要考虑向后兼容性,但是随着业务的发展或需求的变更往往会导致兼容性实现非常复杂,因此引入API版本管理将能解决这个尴尬。下面提供多个版本管理的API实现,不需要再为了向后兼容性而绞尽脑汁。其次,对于API的使用者而言,也可以灵活选择使用不同版本API,而不用担心API的兼容性问题。

WEB API 版本化的五种方式:

方式一:利用URL

HTTP GET:
https://banbenguanli.com/api/v2/useracount/card

方式二:利用用户自定义的request header

HTTP GET:
https://banbenguanli.com/api/useracount/card
api-version: 2

方式三:利用content type

HTTP GET:
https://banbenguanli.com/api/useracount/card
Accept: application/vnd.banbenguanli.v2+json

方式四:利用content type,把版本号分离出来了

HTTP GET:
https://banbenguanli.com/api/useracount/card
Accept: application/vnd.banbenguanli+json; version=2.0

方式五:利用URL里的parameter

HTTP GET:
https://banbenguanli.com/api/useracount/card?v=2

API版本控制策略

任何不断发展变化的API都需要API版本控制策略。API版本可以适应根据API使用者的期望而切换不同版本变得有所不同。建议将以下API版本控制策略作为整体API管理系统的一部分。

1.如果API处于早期测试版本,为了获得消费者的反馈,请建立API各种可能发生的期望。在此阶段内,你会保留这个版本一段时间,因为你的API设计可能还会更改。作为消费者,API是不稳定的,因此他们应该预期到可能会发生的变化。

2.一旦发布,API应被视为契约,如果没有新版本,则不能被替换。

3.突破性的变化意味着客户必须迁移到新版本,请与API使用者沟通更新日期,以确保他们能方便地迁移到新版本。但在某些情况下,新版本的迁移不会马上实现,因此以前的API版本会被继续使用一段时间。

实现版本控制的工具

使用工具和技术可以从根本上实现API版本控制过程。用市场上优秀的API编辑器将使技术开发团队能够在更短的时间内生成并切换更多的API版本,从而不断改进设计决策。

结合工具进行版本控制是大多数开发过程的重要组成部分。API设计领域中也有这种能版本控制的工具,实际上,全球范围内API服务领域中已经存在一些优秀的Web API设计工具。

现在,如EOLINKER、RAML、Swagger,都提供了出色的编辑工具来支持他们的语言。EOLINKER采用的是版本对比和重点标注提示,可以清晰的切换、对比。RAML、Swagger采用的是版本切换,方便程度可能略逊一点。而且只有前者是支持中文的,后两种只支持英文语言。这些API编辑器都能轻松地实现API版本的控制,使得更容易在更短的时间内切换运行版本。

参考资料:

https://dzone.com/articles/when-and-how-do-you-version-your-api

https://cloud.tencent.com/developer/article/1476736

https://blog.csdn.net/hengyunabc/article/details/20506345