让API实现版本管理的实践

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