31

我已经评估了 REST api 的许多版本控制模式（标头、url、...）。到目前为止，最可靠的方法似乎是 url 选项：它适用于代理，并且不依赖于晦涩的模式，例如版本控制的日期。

现在，当我环顾四周时，每个使用基于 url 的方法的人似乎都使用诸如v1、等版本v2。没有人使用次要版本，甚至没有使用语义版本控制等模式。

这提出了一些问题：

  • 你什么时候增加 REST API 的版本号（当然，你对它的更新比五年一次的要多）？
  • 如果您只是修复错误，您可能不会增加版本号，但是您如何区分两个版本？
  • 如果您使用非常细粒度的方法，您最终会得到很多需要并行托管的版本。你怎么处理？

换句话说：像 GitHub 这样的公司如何做到只有v3今天（2015 年），而他们已经经营了 7 年？这是否意味着他们实际上只更改了两次 API？我简直不敢相信。

有什么提示吗？

4

1 回答 1

55

主要版本号是 Web 服务所需的全部内容。因为您的消费者只关心向后不兼容的更改，并且（如果您正确地遵循语义版本控制）这些只会在新的主要版本发布时引入。

所有其他更改（包括新功能、错误修复、补丁等）对您的消费者来说应该是“安全的”。您的消费者不必使用这些新功能，并且您可能不想继续运行包含错误 X 或 Y 的未修补版本超过必要的时间。

在您的 URL 中使用完整的版本号（或您用于 API 版本控制的任何方法）实际上意味着您的消费者必须在您每次对 API 进行更新/错误修复时更新您的 API 的 URL，并且他们将继续使用未打补丁的版本，直到他们这样做。

当然，这并不意味着您不能在内部使用语义版本控制！只需使用第一部分（主要版本）作为 API 的版本号。在您的 URL/标头/其他版本控制系统中包含完整的版本号是没有意义的。

所以回答你的问题：每次发布新版本时都会更新 API，但只有在有新的主要版本时才会发布新的 API 版本。这样，您只需要托管几个不同的版本（当然，随着时间的推移，您可以弃用旧版本）。

于 2015-01-12T12:12:44.660 回答