弃用Web API:最佳做法?


18

最终,您需要折旧部分公共Web API。但是,我对最好的方法感到困惑。如果您拥有大型的第三方应用程序库,仅仅废弃旧版本的API似乎是错误的方法,因为几乎所有应用程序都会在一夜之间失败。但是,您可能无法永远保持古老的Web api的可用性,因为它可能已过时,或者发生了重大更改,因此无法使用它。

淘汰旧的Web API的最佳做法是什么?

Answers:


17

听起来好像原始海报已经有效,但是非正式地弃用了他们的API(任何被称为“旧API”的东西)。但是,在宣布它并通知用户已弃用API之前,不会正式弃用它。

不推荐使用的API是过渡的非活动代码阶段。这是最后的仪式。在这段时期内,采用者/消费者可以重新配置其应用程序以使用较新的API,并欢送告别,从而与该API保持和平。一些API可能会比其他API持续更长的时间,但是目前我们知道它们的时间并不长。

删除的API是一个代码葬礼。它无能为力,只能妥善处理并加以适当纪念。

许多API和服务开发人员选择了代码葬礼,而不是执行最后的仪式。但是,我认为这有些冒险。如果在最初采用或通过续订API /服务时做出了任何形式的服务或支持承诺,您可能希望在履行葬礼之前的一段合理时间内兑现承诺。

对于非服务库,我认为一个主要的发行版本,无论时间长短,都可能是一个可以接受且公平的保证向后兼容性的时期。除此之外,它还取决于用户的影响和游说,以延长其使用寿命。而且,如果由于不可替代的第三方依赖关系陷入困境,并绑定到某些平台的某些版本而引起的反对,也不要感到惊讶。

对于服务,我怀疑您可能希望查看六个月或一年的时间,这仅仅是因为谁可以使用服务的方式和使用方式的差异,以及从使用项目到使用项目的相应开发周期的差异-许多可能正在使用您的服务的项目可能仍会进行大型的前期设计,并且可能会安排超过一年的发布周期。大多数外部开发人员的意见都建议,那些计划很长的人负责满足您的周期时间,而那些耗时长的项目应该采用更快的发布周期,这也许是事实。但是最终删除日期是您必须与用户协商的。

一个好的但不是防弹的弃用策略可能是在宣布弃用时,以相关API部分的调查格式突出显示要删除的时间表以及提出评论或异议的请求。如果由于服务使用[半]匿名访问而没有用户的联系人列表,则可以考虑查看频繁和活跃用户的日志,并将通知分发给主机或域管理员,以按他们认为合适的方式转发。


哇,非常翔实的答案
TheLQ

7

我使用的大多数Web API(来自Google,Yahoo!和Microsoft等公司)都处于“日落”时期。开发人员会在合理的时间内(例如3到6个月)得知将要折旧的功能,以便他们有足够的时间提前进行升级。

您可以在服务条款或其他文档中添加日落时段的详细信息,以便人们了解它的工作原理。这意味着当某人决定使用您的API时,他们将知道他们需要使用什么时间表。例如,您可以通知人们他们将需要每年升级系统一次,并且需要提前4个月通知您。

使用版本编号也是一个好主意,因此您可以说,例如“版本3即将贬值,因此请确保您的代码适用于版本4”。这样,人们就知道他们的应用程序是否适用于版本4然后他们准备好日落了。


1

从过程角度的其他信息:

  • 与所有利益相关者进行沟通:向其他团队和API使用者提供简洁明了的沟通,以说明不赞成使用API​​的原因,策略,计划和时间表的详细信息,版本含义以及替代方法,并相应地设置HTTP。

  • 计划和时间表:在计划中,您应该具有关键的里程碑和计划终止的目标日期。您应该要求使用者使用相同的名称,并提供他们将不赞成使用电话的日期。召开例行会议以监控过程并支持消费者。

  • 版本控制和提供替代方案:版本控制可能有助于显示主要版本的中断更改,并制定API弃用策略。

  • 设置日落HTTP响应标头:HTTP标头充当警告的技术部分,API使用者应监视此类代码以了解何时不推荐使用API​​。

  • 监视之前和之后:监视您的使用者,并提醒任何使用者在一定时间后仍在使用API​​是有用的信息,以确保您不会错过任何废弃软件。


0

除了现有答案外,您还应在删除某些内容时提供直接替换或迁移计划,以便用户可以更新其代码。

尝试避免在没有提供替代方法的情况下删除功能-这会使您的某些用户不满意。


如果您的Web API中有可能,请保持不推荐使用的功能处于活动状态,但让它们返回信息错误,而不仅仅是中断。
询问莫妮卡
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.