API 功能弃用最佳实践

封面图片由 Stephen Edmonds 拍摄，来自 Flickr。

简而言之：与用户沟通！

大多数以编写软件为生的人都有一个共同点：他们不想永远维护自己曾经实现的所有功能。

软件行业的某些部分试图利用这种做法为自己谋利，另辟蹊径——操作系统会尽可能长时间地保持与旧软件的兼容性。“Linux 不会破坏用户空间”，Windows 自带兼容的运行模式，macOS 甚至还有 Rosetta，这款软件允许用户运行在英特尔 CPU 时代之前开发的软件。

甚至有些云服务提供商也尽量减少服务弃用，这样他们就可以始终说“我们不会让您失望”。

停止提供 API 功能的原因有很多，但仅仅是因为我们不是像微软或亚马逊那样规模的公司，就足以成为我们在某个时候停止提供部分 API 功能的理由。

什么是弃用？

弃用某项功能意味着我们告知用户，他们不应该再使用此功能，因为它将来某个时候将被移除。

我们应该问自己哪些问题？

谈到弃用，技术人员通常会考虑实现细节。

“如何在GraphQL中将我的字段标记为已弃用？”

我的 REST 端点是否有弃用标头？

虽然这些问题的答案可以让我们开发出良好的沟通工具，防止 API 的新用户使用这些已弃用的功能，但更大的问题通常是现有用户会发生什么。

他们会检查 API 内部的弃用信息吗？

问题在于，此类措施往往会导致沟通不足。“我们发布了新的主要版本，并将一些接口标记为已弃用，大家都知道这种情况可能会发生，所以这应该足够了。”

所以，以下这些问题更为重要：

• 谁在使用这项功能？
• 对我们来说，保留这项功能有多难？
• 我们的客户愿意支付多少钱来保留它？
• 保留它和丢弃它，对我们的影响有多大？
• 我们希望以多快的速度移除该功能？
• 我们的客户需要多少时间来适应这些变化？

哪些人会受到此次弃用影响？

了解弃用措施的影响至关重要。实现这一目标的方法之一是尽快将消息传达出去。

撰写邮件、博客文章、GitHub issue 和推文，看看用户的想法。我们应该与用户保持持续的沟通，但当事情可能导致用户不满时，这一点就尤为重要。

另一种方法是使用Moesif 等 API 分析服务来了解这些功能的使用情况。

让我们来看一下 Moesif API 分析的以下屏幕截图：

这里展示的是我们 API 端点的堆叠条形图。每种颜色代表一家使用我们 API 的公司，条形的大小表示该公司在过去 28 天内向该端点发送的请求数量。我们可以一目了然地看出哪些是关键 API 端点以及哪些公司在使用它们。

如果我们想要弃用该/reviews/reviews端点，我们发现它只被一家公司使用，我们可以直接与他们讨论我们的弃用想法。

弃用某项功能的主要原因之一通常是没有人使用它，因此这甚至可以是征求用户意见之前的第一步。

弃用前请与受影响者沟通。

接下来，我们应该联系受影响的用户。我们掌握了分析数据，可以直接与使用这些功能的用户沟通。如果我们已经在社交媒体上发布了弃用计划，那么那些目前未使用该功能的用户可能会因为计划将来使用而表达不满。

也可能是潜在客户表示，正是这个功能促使他们最初考虑使用我们的 API。

收集用户意见后，可以将其与公司内部需求结合使用，以制定弃用计划。

宣布弃用

下一步是通知用户即将弃用该功能。

对于许多公司来说，这只是第一步，他们会写一篇博客文章，希望所有受影响的人都能阅读，但这还远远不够！

如果使用Moesif API 分析，我们可以查看哪些用户正在使用我们想要弃用的功能。通常，我们的用户或公司账户都关联着电子邮件地址，因此我们可以直接向这些用户发送邮件，这可能是最直接的方法。

写博客文章、发推文、创建 GitHub 问题、向所有用户发送电子邮件并没有错，因为这能向用户表明你很关心他们。

然后我们可以使用我们 API 类型提供的技术，最终将这些功能标记为已弃用。

另外：别忘了更新文档！

用停电唤醒其他人

最后一种传达弃用通知的方式是断电。

我们撰写了电子邮件，在社交媒体上发布了公告，最终将我们的端点和字段标记为已弃用。

但是，即使我们有几千名用户，也总会有一些用户将我们过滤为垃圾邮件，不在社交媒体上关注我们，并且从不检查 API 是否返回弃用警告。

为了唤醒它们，我们可以使用一种叫做断电的技术。它的工作原理如下：

我们会检查已弃用功能使用率较低的时段。在这些时段，我们会根据使用频率，暂时禁用这些功能几小时或几分钟，然后再重新启用它们。

这可以在该功能最终关闭前一到两个月进行，并导致用户监控出现高峰。

同时，我们也需要让阅读我们电子邮件和社交媒体的用户了解此事，以免我们被他们担忧的信息所左右。

结论

始终保持对话进行！

如果我们与人交谈，即使他们与我们意见不同，他们也会把我们看作人，而不仅仅是没有面孔的公司。

了解我们周围以及我们的 API 正在发生的事情至关重要。

想知道您的 API 实际是如何被使用的吗？
Moesif 让弃用 API 功能变得轻而易举！ 了解更多

本文最初发表于Moesif 博客。