ruby-on-rails - 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

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

Answer 1

The reason to make a real REST API is to get evolvability … a "v1" is a middle finger to your API customers, indicating RPC/HTTP (not REST) -- Fielding, 2013

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

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

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