对API进行版本控制很困难，API领域的每个人都对如何正确地进行版本控制有自己的看法。这也是几乎不可能避免的。当团队构建新软件时，有时他们需要去掉某个特性（或者以不同的方式提供该特性）。版本控制为API用户提供了一种可靠的方法来理解API中的语义变化。虽然有些公司会不遗余力地不改变一个版本，但我们没有这样的奢侈：由于我们运营的API的数量，在这里开发API的团队的数量，以及依赖它们的开发人员的数量，我们对API进行了版本化，以便开发人员知道对他们的期望是什么。

版本化API应该按照一个一致且可靠的标准来进行综合政策。在Google，我们遵循api语义版本控制的一般原则。语义版本控制的原则很简单：每个版本都有一个数字X和一个数字Y。X表示主要版本，Y表示次要版本。新的主要版本表示向后不兼容的更改，而新的次要版本表示向后兼容的更改。

我们的主要版本反映在我们的API路径中，紧跟在域之后。为什么？好吧，这意味着您调用的任何API URL都不会重命名或删除您所依赖的任何字段。如果你要上厕所coolcloudapi.googleapis.com/v1/coolthings/12301221312132，你可以相信，返回的JSON永远不会重命名或删除字段。

当然，这种方法有利弊，许多聪明人对"正确"的版本方法进行了激烈的辩论。有些人喜欢将版本请求编码在头中，有些人则"跟踪"任何单个API使用者习惯于获取的版本。我们已经看到和听到了所有这些，我们共同决定，为了我们广泛的目的，在URL中编码主要版本在大多数时候是最有意义的。

请注意，次要版本不在URL中编码。这意味着，如果我们通过添加一个新字段来增强coolcloudapi，那么有一天当调用coolcloudapi.googleapis.com/v1/coolthings/12301221312132开始返回一些附加数据。但我们永远不会通过删除字段来"破坏"你的应用程序。

当我们发布一个新的主要版本时，我们通常只编写一个后端来处理这两个版本。所有请求（无论版本）都会发送到后端，它使用路径中的版本来决定返回哪个曲面。

对于使用云端点（我们的API网关）的客户，我们开始发布使您能够遵循这些相同版本控制实践的功能。

首先，我们的代理现在可以为您的API提供多个版本，并报告API版本。这将让您看到不同版本的API接收到多少流量。实际上，这意味着您可以知道有多少流量迁移到了新版本。

第二，它可以为您提供一种策略，通过找出谁仍在使用旧版本来弃用和拒绝API。不过，这是另一篇博文的主题。

版本控制是制造更好的API的关键。我们相信我们在内部采用的方法，并乐于与社区分享我们开发的最佳实践。要开始使用云端点，请查看我们的10分钟快速入门或深入教程，或访问我们的Google小组google-cloud-endpoints@googlegroups.com-我们很想听到你的消息！