译者注：本文主要描述了几种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更改应该是什么样子的:
添加新资源。
添加新的事件类型。
为响应添加新的属性。
改变属性的顺序。
向现有方法添加可选参数。