我们的服务已将我们的 api 与我们将支持至少 18 个月的公共版本一起发布。我们现在开始研究 v2 中的一些新功能。
我正在阅读它，但还没有找到答案。
为公共网络服务设计新的 API 版本时
我们的 V2 实体至少具有与 V1 项目相同的所有实体。然而，他们经常为 V2 项目添加一些新属性。考虑到这一点...
当客户执行 v1 API 版本获取时，我们是否应该显示 v2 项目？
他们什么时候做V2 get怎么样？
V2 添加了一些 v1 没有的属性。使用 V2 get，我们是否也应该返回 V1 项目？在那种情况下，我们是否应该将这些属性留空？
这样做的“正确方法”是什么？
【问题讨论】：
标签： api-versioning
我认为 API 应该有所不同。 您无法更改 api v1，因为客户已经在您从 api 返回的内容上实施了他们的软件。 所以你应该实现一个不同的 API，你可以自由地改变你想要的一切。
显然，API 版本必须明确暴露给端点，例如： myapi.api.com/v2/get/articles。 （并且不要忘记不要更改版本 1 的端点）
【讨论】：
在特定的 API 实现中总是存在边缘情况，但如果我们谈论 REST over HTTP，那么存在所述实体的每个 API 版本都应该向前和向后可用。
首先，让我们考虑一个资源。假设您有/order/123。请记住 REST 是代表性的状态转移。 API版本应该不要将其视为二进制代码的版本，也不要将 API 视为被调用的方法。 HTTP是API和GET是方法（想想http.get(request)）。也就是说，API 版本表明如何您希望代表实体。 API 版本最好被认为是媒体类型协商的一种形式。
如果我是客户或与命令API，我并没有特别考虑 API 版本。我只知道我有订单123。无论 API 版本如何，此顺序都存在。客户端代码只关心 API 版本“我知道/期望命令看起来像……”.这意味着所有订单应该在所有版本中可用。此行为可能需要您需要一些特殊的处理或数据传输对象 (DTO) 才能使事情按预期通过网络进行。如果可能的话，这可能是隐藏/删除新成员或填补缺失的成员。这可能会导致很多额外的工作，这就是为什么拥有一个健全的版本控制策略（如N-2）很重要的原因。
您已选择按查询字符串进行版本化，这使您处于一个非常有利的位置。使查询参数在所有版本中都是必需的是一个很好的策略，因为客户端应该总是必须明确地询问他们想要什么。我们都知道当服务器发生什么假定.尽管很受欢迎，但按 URL 段进行版本控制是最糟糕的版本控制方式。它违反了统一接口REST 约束。资源由其 URL 路径（整个路径）标识。人们将 123 视为标识符，但对于 HTTP 而言，它是 order/123。 v1/order/123 和 v2/order/123 不是不同的顺序（如 URL 所暗示的），而是不同的交涉.查询字符串从不标识资源，因此这是一种合理的（如果不是务实的）版本控制方法，而不是真正的媒体类型协商。
【讨论】：