API版本控制和存储数据

Question

在公开不同的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版本？

Answer 1

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

因此,问题现在成为编程语言API版本控制的问题,并且不受Web服务特定的考虑因素的影响.

然后,我将使接口的名称包含版本号,如在MyWebServiceInterfaceV1中.

一旦将一个版本的接口发布到外部世界,("它在野外是免费的",可以这么说),包含接口的源代码文件夹被锁定在源代码库中,这样就没有人可以再次修改它永远.然后你制作一个界面的副本,然后增加它的版本号,从那一刻起,所有的新工作都在新版本上完成.

所以,我们现在正致力于MyWebServiceInterfaceV2.

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

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

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

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