9

在公开不同的 API 版本时,您如何处理存储和检索可能具有不同结构的数据?

假设我们有两个 API 版本;V1 和 V2。V1 和 V2 都有一个位于“ https://api.com/message ”的 POST 端点,它将根据传递的数据在数据库中创建一条消息,例如:

{
    DOB: '2014-12-01'
}

在 V1 中,所需的数据与 V2 不同,因为在 V2 中,我们决定将 DOB 从格式为“YYYY-MM-DD”的字符串更改为整数时间戳,例如 1284723728323

在这种情况下,当我们从使用 V2 API 的调用中保存数据时,DOB 字段将是一个整数,但从对 V1 的调用中保存时,它将是一个格式非常不同的字符串。

随着 API 的每次迭代,我们可能会修改底层数据的许多方面。调用较旧的 API 版本将导致存储的数据对于其他版本的 API 不正确。

是否有一种优雅的方式来处理需要不同格式/结构的数据的不同 API 版本?

4

2 回答 2

6

我首先要做的是确保每个面向 Web 的 API 对应interface于真实编程语言(例如 Java)中的实际 API。

所以,这个问题现在变成了编程语言 API 版本控制的问题,并且没有特定于 Web 服务的考虑。

然后,我会让接口的名称包含版本号,如 MyWebServiceInterfaceV1。

一旦接口的一个版本发布到外部世界,(可以这么说,“它在野外是免费的”)包含该接口的源代码文件夹被锁定在源代码存储库中,因此没有人可以再次修改它, 曾经。然后你制作一个接口的副本并增加它的版本号,从那一刻起,所有的新工作都在新版本上完成。

所以,我们现在正在开发 MyWebServiceInterfaceV2。

对于您引入的每个新版本的接口,您还编写了一个转换器类,它实现了旧接口并映射到新接口,并且您继续维护该类,直到新接口也被锁定。

因此,从 V1 到 V2 的转换器类必须能够将字符串日期转换为整数日期,也可能反过来:整数日期到字符串日期。这里要意识到的重要一点是所有转换都应该是可能的;如果似乎不可能进行转换,那么这意味着您计划在一个方向上进行更改,这将使您的系统不向后兼容旧版本。只要您在所有新设计中牢记向后兼容性,所有必要的转换都应该保持可能。

如果您有 N 个版本,您可以实现 (N-squared)/2 个不同的转换器,以便能够直接从任何版本转换到任何较新的版本,或者您可以只有 N 个转换器,每个转换器只能转换在两个连续版本之间,并根据需要堆叠尽可能多的版本,以便逐步从非常旧的版本升级到最新版本。

当然,在任何给定时间,只有最新版本的接口由与实际数据库通信的实际实现支持。

于 2015-02-09T15:04:15.750 回答
4

API 版本接受的表示不应与数据在后端的存储方式相关。我会这样做:

  • API 的 V1接受并生成 YYYY-MM-DD 字符串作为日期。
  • API 的 V2接受并生成 1284723728323 整数作为日期。
  • 两个版本的 API 将它们的格式映射到和从一个通用的存储类型
  • 如果必须更改公共存储类型(例如从字符串到 int),则会执行内容迁移以及映射代码的任何必要更新。
于 2015-02-09T14:59:32.040 回答