REST Api 和语义版本控制答案

【问题标题】：REST Api and semantic versioningREST Api 和语义版本控制
【发布时间】：2019-10-25 01:05:22
【问题描述】：

我的团队已经构建了多个 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

？我的印象是语义版本控制是内部的，不一定需要向消费者公开......这只是使用标签的问题吗？

【问题讨论】：

标签： ruby-on-rails rest api semantic-versioning

【解决方案1】：

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

REST 的部分观点是标识符 (URI) 可以只是标识符，并且域应用程序协议由超媒体描述。

所以是的，如果你“正确地做 REST”，那么语义化版本的 URI 就是浪费每个人的时间（因为就客户端而言，URI 是不透明的。记住，URI 缩短器工作 em>.)

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

【讨论】：