ruby-on-rails - REST Api 和语义版本控制
问题描述
我的团队已经构建了几个 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 文件?或者,如果更改是向后兼容的,那么更改是否应该在 animals_controller.rb 内部v1.0.0
?但如果我们这样做,那么真的不应该只是:
/controllers
/api
/v1
animals_controller.rb
? 我的印象是语义版本控制是内部的,不一定需要向消费者公开......这只是使用标签的问题吗?
解决方案
制作真正的 REST API 的原因是为了获得可进化性……“v1”是 API 客户的中指,表示 RPC/HTTP(不是 REST)—— Fielding,2013
REST 的部分要点是标识符 (URI) 可以只是标识符,并且域应用程序协议由超媒体描述。
所以是的,如果你“正确地做 REST”,那么语义化版本的 URI 就是浪费每个人的时间(因为就客户端而言,URI 是不透明的。记住,URI 缩短器有效。)
版本控制往往很重要的地方在于链接关系和媒体类型的语义。试图在那里引入向后不兼容的更改会造成巨大的混乱,因此需要做很多工作来保持兼容性(HTML5 仍然如此text/html
),并且最好通过引入新名称(text/not-html-anymore
)来实现破坏兼容性。
推荐阅读
- powerbi - DAX Measure 用于计算制造和产品中的不同特征数
- python-3.x - multiply(a, b) 函数的时间复杂度
- matplotlib - 与在 jupyter notebook 中渲染相比,保存后 Matplotlib 图形看起来不同
- c - C 和 Masm 程序
- python - python sdist 中应该包含哪些文件?
- java - 对正则表达式感到困惑?如何阅读正则表达式
- web-services - Web 服务 Eclipse
- python - 如何使用OpenGL和Python通过(XYZ)坐标绘制折线
- java - 为每个用户更改一个变量
- python - 多个 GUI 来回通信