API版本控制

译者注：本文主要描述了几种API版本控制的方法。用户能够查询原始的API，或者添加定制的头文件来接收特定的版本。若是应用程序收到一个重大修订，将URI修改成V2。在进行迭代改进时，将建立与更改日期相一致的端点，并容许用户将日期信息附加。而后，能够选择保留旧版本的时间。并且在设计和版本化API时，您能够应用许多不一样的理念。如下为译文

API设计是一个“火辣热门”的话题！关于API的最佳结构和版本的方法已经有不少优秀的文章介绍过了。在这篇文章中，咱们将会深刻研究不一样的API设计之间有哪些冲突的地方，并在此基础上提出咱们的中立观点，而后展现咱们是怎样使用FLY去验证咱们的中立观点的。

API版本控制
虽然没有一个统一的方式来设计API，可是有必要明确一下许多开发人员赞成的几个关键想法。一个结构良好的Web API应该是…

1：与客户端保持持续的协议。协议能够保证一致性和稳定性；客户端应该可使用API，而不用担忧它会忽然中断或消失。

2：更改或升级后向后兼容。对新端点的旧查询仍应产生预期的返回值。

3：RESTful（互联网应用程序）。它应当能够识别HTTP的相关动做 ：GET，PUT，POST，PATCH，DELETE等。

为了最好地实现这些理想的要求，在如何实现不一样版本的API上就是仁者见仁，智者见智了。咱们来看看它们中的三个…

URI版本控制

curl https://example.com/api/v2/lists/3
经过解除URI中的版本号，客户端能够访问/v1/或/v2/API。它可读，适应性强，可直接插入用户浏览器。

Header版本控制

curl https://example.com/api/lists/3 \
-H 'Accept: application/vnd.example.v2+json'
API URI保持不变。头版本控制主要是经过自定义的Accept HTTP头来完成的。核心URI仍然保持不变，可是能最好表示出API的资源，而且版本的更改将经过头和响应类型传递。

没有版本控制！

curl https://example.com/api/lists/3
你须要什么版本？让咱们扩展咱们的API以适应新的或调整的案例！放弃旧的框架，选择创建和扩展。

中立观点
每个方法都是合理的，若是有好的设计思路的话，它们均可以呈现优异的API。 最终，咱们但愿它们都能实际运用起来，尽量快地传输信息。一个没有版本控制的绿色API可能会变得混乱，因此咱们将远离这一点。相反，咱们将接受URI和HTTP标头中的版本控制。做为一个转折，咱们将使用一个自定义的HTTP头。

为了不出现连咱们本身都没法了解为何请求会如此混乱且冗长的状况出现，让咱们更深刻地了解一下为何咱们要使用这种方法。咱们的方法是基于这样一句格言:随着太阳的升起，你的应用将会改变。

咱们来看一个例子。

MightyList

咱们正在为虚构应用程序MightyList构建API。在它简陋的早期，Mighty List容许用户建立列表。它具备从URI提供的API做为mightyapp.com/api/v1/。您可使用API来请求列表信息，以下所示：

curl https://mightyapp.com/api/v1/lists/3

...

{
"listId": "3",
"shopping": "Shoes, tie, umbrella, snorkel",
"leisure": "Skiing, surfing, snorkeling ",
"food": "bananas, peanut butter, spinach",
"cost": "One hundred dollars"
}
在开发咱们的应用程序时，咱们能够指望更改两种类型：小版本调整和大版本调整。咱们来看看一个小版本调整的例子，使用咱们上面的示例响应，其中list 3的GET请求返回了shopping, leisure, food和cost的字符串值。开发团队但愿调整数据模型，cost如今变成了整数而不是字符串了。

curl https://mightyapp.com/api/v1/lists/3

...

{
"listId": "3",
"shopping": "Shoes, tie, umbrella, snorkel",
"leisure": "Skiing, surfing, snorkeling ",
"food": "bananas, peanut butter, spinach",
"cost": 100
}
此更改会破坏咱们API的向后兼容性！若是有人将MightyList API应用到他们的应用程序中，那么接收一个整数而不是字符串可能会致使他们的应用程序中断。为了不出现这种意外的状况，任何破坏咱们向后兼容性的微小变化都须要对新版本进行bump version。

另外一个须要考虑的状况是大版本调整：MightyList版本2正在进行中。lists将成为superlists，咱们也添加了不少新的资源:bots，ai——等等许多奇特的东西。这个重大升级确定会对兼容性产生重大影响; 这是一个全新的应用！

这两个示例都揭露了在改进API时如何保持URL是最新的难度。小版本修改是否会破坏咱们的URL版本？这样最终会有不少版本。咱们但愿保持向后兼容性，但随着应用的不断发展，它将变得愈来愈困难。

在咱们讨论这个问题以前，让咱们定义一个安全的和向后兼容的API更改应该是什么样子的:

添加新资源。

添加新的事件类型。

为响应添加新的属性。

改变属性的顺序。

向现有方法添加可选参数。

当经过选项或全新的资源或事件参数添加新事物时，您可彻底不用担忧与客户端创建的协议，由于它很是稳定，也不会产生任何变化。他们能够继续访问API资源，也会获得预期的响应。若是咱们更改了现有资源或预期的响应内容，咱们须要在API版本中把这种更改给展现出来。

为了使咱们的应用程序的状态清晰，咱们但愿在URI中有一个表示基本产品版本的版本；当您的产品从根本上改变时，URI版本将会更改。 MightyList V1使用/ api / v1 /。 MightyList V2使用/ api / v2 /。

为了使咱们的API的当前版本清晰，咱们将使用自定义的HTTP头来表示较小的修订。这相似于让用户请求应用程序版本V2.x。X是API的版本。

在两个地方进行版本控制是一种实用的作法；您的应用程序将迭代，而且老是有可能变成更大的东西。咱们来看看Fly如何轻松地作到这一点。

Superfly API版本控制
在Fly里面，每一个站点都由多个后端组成。您可能在GitHub上有一个静态页面，应用程序使用了Kubernetes集群或Heroku部署，而且还用了一个或多个数据库对数据进行管理。

构建API时，您能够经过对API进行解耦，并将其做为本身的后端主机，这样API的可扩展性和负载平衡的优点就会获得改善。对API解耦也使得版本控制变得相对容易一点。

首先，咱们将为最初的API/api/v1/添加一个新的后端。 咱们将指定相关路径去匹配/api/v1/。若是有多个冗余实例须要负载平衡，咱们能够将它们视为独立的后端进行添加，设置相同的路径，而后调整优先级。若是想要实现这种想法，咱们可使用Fly Middleware根据设备或地理信息，将用户路由到各类API后端。

 

上面咱们建立了一个基线API端点。咱们还但愿为API V1的最新版本建立一个后端。咱们将以04-05-2017为终点。在此以后，咱们能够设置API路由规则。

 

如今，要为第二个后端配置FLY路由规则，以便让那些附加了自定义头文件的用户能够收到最新版本的API。咱们将使用头名称API-Version，由于它能让用户一眼看出其含义，让用户容易记住，也比较清晰。APIAPI-Version头文件将是年月日或04-05-2017的形式。这样作将容许咱们为API建立一个公共的变动日志。用户能够经过更改日期来获取他们须要的端点。

 

太使人兴奋了！咱们已经将API-version设置为04-05-2017，若是头文件中出现了这些信息，用户就会被路由到API V1 - 04-05-2017的后端。用户如今能够选择请求API的特定时间点，同时保留从example.com/api/v1 URI获取原始API V1的能力。您能够查看咱们第一个API后端的原始路由规则：

 

总结
让咱们回顾一下：不一样的API有不一样的端点。用户能够查询最初的API，或者添加定制的头文件来接收特定的版本。若是应用程序进行了一次大版本的调整，咱们将正式地将URI修改成V2。

在进行迭代改进时，咱们也会按照修改的日期同时建立一个端点，并容许用户将日期头文件信息附加到上面。而后，咱们能够选择旧版本能够保留多久，免费催收系统之后在不考虑向后兼容性以及不影响用户使用的状况下，能够选择合适的时间删除它们。

在设计API版本时，您能够应用许多不一样的理念。使用本文中的实例，您能够看到基于Fly头文件或URI后端路由的这些灵活性，可让你实现关于“PI体系结构和版本控制方案”最疯狂的梦想。