关闭旧API的正确方法

一切都结束了，甚至HTTP API也是如此。无论您的API在今天有多棒，有一天您都希望发布一个全新的版本，一个经过改进但不兼容的终结点，一个可以更好地解决同一问题的新参数，或者完全关闭您的API。您当前的API不会永远有效。

不过，您的API有客户端，这很不方便。如果您关闭端点，参数或整个API，而没有正确警告它们，那么它们将非常不高兴。

您如何安全地关闭API，以使其对您的用户尽可能简单？

有正确的方法来执行此操作，包括由令人兴奋的新IETF＆＃34; HTTP API的构建块＆＃34;标准化两个新的草稿标头。工作组，旨在帮助完成这一确切过程。让我们来看看。

希望您有一些API指标，或者至少在某个地方记录日志。如果您不添加，请添加一些！如果这样做，您可以确定没有人再使用此API，那么您将获胜。现在将其关闭，删除代码，跳过本文，小憩片刻。

如果您没有睡午觉，那么下一个问题是问自己：是否有替代此API的替代方法。您关闭的所有内容都会破坏某人的代码并花费时间进行修复。如果API继续运行，则对于客户端生态系统和整个Web的健康都是有益的。

在许多情况下，可以在内部转换旧的API，从而透明地将请求转换为对新API的调用，而无需维护两个完全独立的版本。这是Stripe API版本控制方法的基本组成部分，该方法包括所有API更改的转换，以确保对不兼容的旧版本的请求继续像以前一样工作，并自动转换请求和响应以根据需要使用更新的代码。

这样的翻译并非总是可能的，永远这样做可能会带来极大的额外复杂性，但是如果您能够做到，则可以为您的用户提供宝贵的稳定性，并且避免了很多弃用或过时的工作保养。

但是，如果该服务/端点/参数在生产中正在使用，并且持续支持它是不切实际的，那就必须走了。

他们应该何时开始从该API迁移？您提议的替代品是否可以立即使用？

截止日期是几点？即该API何时会完全停止运行？ （如果您还不太确定，则可以延迟一点答案）。

通过电子邮件发送您的邮件列表，将其发布到Twitter上，如果有的话，更新您的API规范（例如，OpenAPI的操作和参数字段已弃用），并在在线相关文档中大声地突出显示。

您应该包括上面的所有信息：它们应该做些什么，何时建议他们开始迁移以及必须迁移的截止日期（如果有的话）。

告诉人类后，就该告诉计算机了。这是新的IETF标头出现的地方。

“不赞成使用”标头告诉客户端所请求的资源仍然可以像以前一样工作，但是不再建议这样做。您可以使用单个HTTP标头非常简单地说明这一点：

或者，您可以提供日期。该日期告诉用户何时应该开始迁移到其他地方。可以是过去（如果他们应该立即开始迁移）或将来（通常意味着他们应该迁移到的东西还没有准备好）。像这样：

如果您不赞成使用整个端点或服务，则只需在每个响应中将其返回即可。如果您不赞成使用特定功能，例如参数，请求方法或请求正文中的特定字段，那么您只想在使用该功能时在请求中返回该功能。

要向客户端提供更多信息，您可以使用Link HTTP响应标头链接到端点或其他地方的可读文档。您可以在同一个Link标头中组合使用多个逗号，只需用逗号分隔即可（稍后将看到完整的示例）。规范定义了4个与弃用相关的链接：

这是告诉您的用户正在发生的事情以及他们应该怎么做的主要方法。您几乎总是想使用它！如果您还没有完整的详细信息和最终的关闭日期，那么即使是占位符也将有所帮助。在这种情况下，请不要忘记让用户使用邮件列表或RSS或类似内容来订阅更新，这样，一旦准备就绪，他们就可以听到有关完整计划的信息。

如果您希望客户端移动到API相同端点的最新版本，请使用此命令将它们指向那里，如下所示：

如果您有多个版本的API，通常一次迁移一个版本通常会更好，而不是直接从最早的旧版本过渡到最新的版本。为了解决这个问题，您可以链接到不建议使用的端点的下一版本，而不仅仅是最新版本，如下所示：

如果此API没有新的等效版本，并且用户应迁移到完全可以替代的完全不同的资源，则可以使用备用链接指示：

一旦知道API何时完全关闭，就应该添加一个Sunset标头。

Sunset标头会告诉客户端何时停止运行。这是一个艰难的截止日期：API客户端必须在此日期之前转移到其他地方，并且您保证在此之前不会破坏任何内容。

您必须在此处提供日期，并且应该在将来。如果是过去的话，那还是可以的：在那一点上，您实际上是在说＆nbsp;＆nbsp;这可能会在您需要立即停止使用的任何时候关闭。看起来像这样：

这非常简单，不仅可以用于关闭API：您还可以使用它来表示将来会进行URL迁移的HTTP重定向，或者表示某些URL的生存期有限（对于那些本质上是临时的，或出于监管原因（例如某些资源的数据保留政策）。它只说＆＃34;此端点在此日期之后可能会停止做您期望的事情，请准备好＆＃34;。

该规范还提供了日落链接关系。该链接旨在链接到有关关闭该特定终结点的计划的更多信息（如果有的话，可能与弃用链接相同的文档），或有关服务的常规日落策略的更多信息。像这样：

这是指出常规日落政策非常有用的好地方！日落策略会告诉客户，当您关闭端点时（例如，替换开始生效一年后），用户应如何确保他们听到此信息（邮件列表，状态页面，HTTP标头，您可以为其命名），以及通常应如何处理（更新，检查文档，遵循链接标题）。

现在添加一个并不能帮助您弃用，但是如果您在一年前发布，则您的客户已经准备好了。现在是发布日落/弃用策略的第二好的时间。如果您仍在编写弃用文档，则可能值得考虑。

这些部分设计为可以很好地协同工作。例如，要表明一个API最近已被弃用，将在6个月内关闭，链接到文档，并提供直接链接到下一个版本，您应在响应中包含以下标头：

弃用时间：格林尼治标准时间2021年1月21日星期四23:59:59日落时间：格林尼治标准时间2021年7月20日星期二23:59:59链接：＆lt; https：//api.example.com/v2/customers> ;; rel =＆＃34; successor-version＆＃34 ;,＆lt; https：//developer.example.com/shutting-down-customers-v1> ;; rel =＆＃34;弃用＆＃34;

一旦一切就绪，并且您的日落截止日期过去了，您就可以开始了。

但这并不意味着您需要立即完全终止该API。逐步关闭可以帮助确保仍在使用此API的所有客户端在完全消失之前获得最后机会警告。 GitHub在2018年删除一些加密支持时做到了这一点：首先，他们将其禁用了一个小时，然后重新启用，然后两周后将其永久禁用。

还有其他窍门：Android在2015年为已弃用的本机API增加了越来越多的延迟，最终等待了整整16秒的等待时间，才最终完全关闭了该API。这些逐步关闭会为错过您的最后期限的客户提供一点灵活性，并可能帮助尚未注意到弃用现场的客户并在API完全关闭之前解决问题。

无论哪种方式，只要您已尽力而为，就可以传达关闭的信息，现在该关闭端点/功能/整个服务，删除代码，最后小睡一下。

像这样仔细地进行弃用和关闭操作，可以使您的客户端尽可能清楚地知道他们如何依赖您的API，何时需要采取行动以及需要做什么。这些变化可能很重要，并且此信息很重要！

这些新的标题标题使我们不仅可以与人类进行交流，还可以将这些信息公开给自动化系统。随着这些标头的普及，我很高兴开始看到在它们之上构建更多的工具。通用HTTP客户端可以根据这些数据自动记录有用的警告，API生成器本身可以根据API规范为您处理越来越多的警告，HTTP调试器（如HTTP Toolkit）可以在截获的实时流量中为您突出显示不赞成使用的端点的用法。这是一个令人兴奋的时刻，开始关闭一切！

重要的是要注意，这些标头是HTTP规范草案。在最终确定之前，它们可能会更改。就是说，他们已经经历了几轮修订，从现在开始它们不太可能会发生巨大变化，现在是时候开始在野外进行测试了。

但这确实意味着仍然需要反馈！如果您对它如何工作以及如何更好地工作有任何想法，请与＆＃34; HTTP API的构建模块取得联系。工作小组。您可以通过[email protected]通过电子邮件发送邮件列表，或在此处滚动以前的邮件列表讨论。

调试，集成或构建HTTP API？拦截，检查和一键式使用HTTP Toolkit模拟HTTP。