REST Api和语义化版本控制

Question

我的团队已经构建了几个API，现在它们都已经公开。我们正在为其中一个API添加功能，这些功能对于我们现有的客户来说不会有任何破坏性影响，因此根据 https://semver.org，这将被视为较小的更新。我们现在意识到我们想要遵循语义化版本原则。我们还在使用URI版本控制。假设我们现在处于 v1.0.0 版本，现在我们需要将其更新到 v1.1.0 版本。根据其他帖子的建议，如果我们决定仅在路由中期望主要版本号，例如 /api/v1/animals，但是所有客户端都将升级到最新版本的v1，因为它应该向后兼容，这告诉我语义化版本控制是在内部处理的。通常如何处理这种情况？我们有一个Rails应用程序，如果我们的结构是这样的：

/controllers
  /api
    /v1.0.0
      animals_controller.rb

如果我们升级到小版本v1.1.0，是否应该创建一个新的v1.1.0文件夹，并在其中放置一个新的animals_controller.rb文件？或者如果更改是向后兼容的，那么更改应该在v1.0.0内的animals_controller.rb中吗？但是如果我们这样做，那么真的不应该只是：

/controllers
  /api
    /v1
      animals_controller.rb

我得到的印象是语义化版本控制是内部使用的，而不一定需要向消费者公开...只需使用标签即可？

- Kay E

Answer 1

制作真正的REST API的原因是为了获得可扩展性...“v1”是对API客户的中指，表示RPC/HTTP（而不是REST）--Fielding, 2013 REST的部分重点在于标识符（URI）可以只是标识符，并且超媒体描述了域应用程序协议。

因此，如果您正在“正确地执行REST”，那么语义化版本的URI就是浪费每个人时间的事情（因为对于客户端来说，URI是不透明的。请记住，URI缩短器有效）。

版本控制通常很重要的地方在于链接关系和媒体类型的语义。试图在这里引入不兼容的后向更改会造成巨大的混乱，因此需要进行大量的工作以保持兼容性（HTML5仍然是text/html），并且最好通过引入新名称（text/not-html-anymore）来实现破坏兼容性。

- VoiceOfUnreason