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，是否应该在其中包含新的animals_controller.rb文件的情况下创建一个新的v1.1.0文件夹？或者，如果更改是向后兼容的，那么更改应该在v1.0.0内的animals_controller.rb中吗？但是，如果我们这样做，那么真的不应该只是：

/controllers
  /api
    /v1
      animals_controller.rb

？我给人的印象是语义版本控制是内部的，并不一定要暴露给消费者...这仅仅是使用标签的问题吗？

Answer 1

制作真正的REST API的原因是为了获得可扩展性……“ v1”是API客户的中指，表明RPC / HTTP（不是REST）-Fielding, 2013

REST的一部分在于标识符（URI）可以仅仅是标识符，并且域应用协议由超媒体描述。

所以，如果您“正确地执行REST”，那么语义版本化的URI浪费了每个人的时间（因为就客户端而言，URI是不透明的。请记住，URI缩短器work。）

版本控制很重要的地方在于链接关系和媒体类型的语义。试图在其中引入向后不兼容的更改会造成很大的麻烦，因此需要做很多工作来保持兼容性（HTML5仍为text/html），并且最好通过引入新名称（text/not-html-anymore）来实现破坏兼容性。 >