如何对依赖于接口的REST进行版本？

Question

关于REST版本控制的文章倾向于描述三种版本控制方法。

1. 将版本包含在URL：example.com/api/v1/myresource中
2. 若要将版本包含在标题中，请执行以下操作
3. 将版本包含在内容类型中

我正在构建的应用程序有两个部分：

1. 用户可以根据需要更改以JSON格式存储的设置的界面。
2. 用户可以用来获取资源和编辑数据的API。

API严重依赖于接口。换句话说，如果我更改了接口(例如，重命名了一些JSON字段)，API可能会改变它的行为，甚至中断。

所有这些方法都假设API版本不依赖于接口，因为具有任何接口的用户可以同时使用多个API版本。

我的问题是，当API依赖于您的接口时，您如何处理版本？

我想出的最佳解决方案是使用户能够在设置中选择他们的版本。通过这样做，我可以使用相应的API方法为适当的接口提供服务。

API版本控制的最佳实践？描述了我前面提到的三种方法。据我所知，他们没有谈到如何对依赖于接口的API进行版本化(例如，API v6必须与接口v6一起使用)。

Answer 1

通过使API更容易被发现，您可以应用一些策略来最小化破坏的更改：

超媒体约束-使用类型化链接导航和使用版本的媒体类型:帮助您在Richardson的成熟度模型(http://martinfowler.com/articles/richardsonMaturityModel.html)上移动更高的位置。目标是允许源服务器在不破坏客户端的情况下改变它对生成的URL的看法。因此，不需要硬编码您的URL中的版本号，只要给一个知道的URL，然后链接到适当的版本，如果您真的需要一个URL。如果您设计与业务概念相关联的操作，这也很有趣。

语义版本控制--只有当您有“突破性更改”(参见http://semver.org)时，才应该更改的版本，这给出了一些有趣的指导方针。

更新契约/数据结构-为了添加/删除JSON字段，还可以查看Google缓冲区>语言指南>更新消息类型:当涉及到公开结构化字段/数据时，有一些规则可以应用于媒体类型(甚至链接类型)。

最终取决于你的观众。有些可能有一些技术限制，而更改可能真的会影响到它们，而另一些则更灵活，并且可以很容易地适应。

因此，要了解您的具体问题:您所描述的内容似乎有点像“特性开关”，请参见http://martinfowler.com/bliki/FeatureToggle.html。您启用了一个特性和行为更改。如果您使您的API可被发现(基于您在所谓的“接口”中启用/禁用的内容而出现和消失的链接)，您可以使用上面提到的一些指导方针来减轻中断的更改。在问题域/业务概念上对API进行建模比仅仅建模纯数据(CRUD)操作更稳定。在API上使用更高层次的抽象(业务概念与低级数据操作)

因此，也许您应该重新考虑您的用户真正需要什么，例如，将这些选项集成到一个可发现的API (而不仅仅是入口点)中，其中选项在特定的上下文中启用/禁用/配置。

Answer 2

您可以选择更适合您的版本控制方法(包括URL中的版本、在标题中包含版本或在内容类型中包含版本)。

当资源URL更改或JSON属性更改时，应考虑发布API的新版本。

有时，您可能会从一个版本更改为另一个版本。因此，请考虑适当地记录这些更改，并考虑同时支持几个不同的版本。如果客户端使用不受支持的版本执行请求，请考虑向他们提供适当的错误消息。

例如，看看Facebook更改量g。从一个版本到另一个版本，JSON属性名称已经更改，其中一些已经被取消推荐，然后被删除，新的属性也出现了。API端点也发生了类似的事情:其中一些被重命名，然后被删除，新的被添加。客户端需要更新代码以使用API。升级指南永远是受欢迎的。

只是想给你一些见解，那是Facebook如何支持其API的多个版本

版本时间表 每个版本保证至少运行两年。在下一个版本发布的两年后，版本将不再可用。 因此，如果API版本2.3于2015年3月25日发布，API版本2.4于2015年8月7日发布，那么v2.3将于2017年8月7日到期，即在版本2.4发布两年后。 对于API，一旦一个版本不再可用，对它的任何调用都将默认为下一个最老的可用版本。下面是一个时间线示例：