首页 博客 组织需要了解什么...

组织在弃用 API 时需要了解什么

Keshav Vasudevan
  2017 年 1 月 11 日

API 领域经常出现的一个话题是公司决定弃用 API 的版本，或完全停止对流行 API 的支持。 以最近的 Google 为例，它悄悄宣布将在 2017 年 1 月停止对其 Hangouts API 的支持。据推测，此举是为了专注于其消费者视频聊天应用 Duo，这导致 Hangouts 成为企业级解决方案。这给基于该 API 构建的应用程序（如 Roll20 和 PingPong）带来了很多不确定性。 公共 API 最好被认为是一个业务部门提供给另一个业务部门的合同，由提供服务的公司定义。各种第三方开发者和合作伙伴部门可以使用这些 API 来构建他们自己的服务。 “开放 API”的概念一直是应用程序开发者创新的驱动力，但同时也带来了一定的风险。使用公共 API 构建应用程序或服务最大的风险之一就是其不可靠性。作为向公众提供 API 的组织，制定一个计划来管理不同 API 版本的弃用和淘汰非常重要。那么，组织如何最好地弃用 API？让我们首先了解 API 弃用背后的原因，然后重点介绍一些有效弃用的推荐做法。

何时弃用 API

弃用和禁用 API 的决定是艰难的。没有正确的方法可以做到这一点，但肯定有错误的方法。请记住，如果 API 的弃用处理不当，可能会损害公司的品牌声誉和信任。 进行 API 弃用的原因有很多。弃用 API 版本可能是因为：

  1. API 不安全
  2. API 有太多错误
  3. API 不支持重要的用例
  4. API 效率低下

在当今快节奏的科技领域，弃用 API 版本或多或少是既定的，其中不断向 API 添加新的和更新的改进以保持其相关性。如果快速提供具有适当资源的良好且稳定的替代方案，这种形式的弃用不会对消费者的应用程序产生太大影响。 然后还有更永久的弃用形式 — 完全删除或禁用 API。在这种情况下，API 将被完全处置，不提供更新版本。这是一个风险更大的选择，如果组织想要进行此操作，则需要对这样做的影响有充分的了解。 API 被处置的一些原因是：

  1. 由于成本原因，该服务不再能被支持
  2. 公司决定将资源投入到该产品的不同变体中
  3. 该服务不再服务于业务目标

这些决定通常归结为业务战略以及 API 与公司的收入或用户获取目标的协调。虽然这个决定很艰难，但很多组织迟早都必须经历它。

如何高效地弃用 API

弃用是 API 的最后阶段，应该谨慎和同情地进行。它可能会给您的最终用户带来很多挫败感，在某些情况下，甚至会导致整个产品的关闭。以下是一些更好地执行此操作的指南。

坦诚沟通  

当您决定弃用 API 时，请与 API 的使用者公开坦诚地沟通。发送一条初始消息，宣布计划弃用，以及建议的弃用时间范围、下一个版本发布计划（如果有）以及其他信息，如支持、联系信息等。API 管理工具可以在此派上用场，可以快速访问使用过您的 API 的用户列表。如果此信息不易获得，查看 API 日志中频繁用户可能是一个不错的起点。  也可以在 API 开发者门户及其文档中进行沟通。例如，Swagger 框架支持操作的弃用标签，该标签将更新交互式 Swagger 文档，通知用户已弃用的操作。 您可以在规范文档中了解更多信息。  Swagger UI

提供足够长的日落期

这是最初宣布弃用 API 后的时间段，它使 API 使用者有时间重新配置其应用程序。这可能是以代码更新的形式，使其适应新版本的 API 进入他们的软件架构，或者是一个在 API 被禁用时适应替代解决方案的程序。良好的日落期非常重要，因为它使依赖 API 的公司有时间调整其业务和技术策略。根据弃用 API 的覆盖范围、用户群和服务产品，此期间可能在 3 到 8 个月之间。

有效版本控制

通过有效的版本控制，弃用 API 的特定版本会更容易。通过良好的版本控制，也可以使不同版本的 API 同时存在。在完全弃用 API 之前，构建并发布 API 的下一个版本。这与日落期相关，为开发人员和工程师提供了足够的时间来修改其现有架构以支持新的 API。 SwaggerHub 具有一个 API 版本控制系统，该系统允许 API 的多个版本和迭代同时存在，同时提供友好的元信息来通知最终用户最新、稳定的 API。这是向最终用户提供有关 API 存在的各种版本以及推荐使用版本信息的最佳方法之一。

提供替代方案

可能有许多应用程序和全面的软件解决方案依赖 API 来平稳运行。为您的 API 用户制定一个良好的迁移计划，以便他们顺利过渡到 API 的最新版本，或者在 API 完全删除的情况下过渡到其他替代方案，可以帮助缓解用户的沮丧情绪，并维护他们对您的信任。在 API 完全弃用之前，始终遵守 API 服务级别协议中做出的任何承诺都是一个好主意。这样做的原因是为了维持信任，并在您的 API 用户中保持您组织的声誉完好无损。人们会口口相传，而糟糕的口碑可能会对品牌形象造成不可弥补的损害。Twitter 就是一个突出的例子，它过去曾因与开发者关系不佳而饱受批评，并且正在积极努力重建这种关系。              总而言之，组织应该认真思考为什么要禁用 API 支持、何时禁用以及如何禁用 API 支持，无论是某个版本还是整个服务本身。组织应该花费时间和精力，通过提供正确的信息、正确的资源和正确的时间来帮助最终用户恢复。最后，组织应该投资于管理、版本化和最终淘汰其 API 不同版本所需的正确工具和基础设施。  

API 经济以及如何优化您组织的 Swagger API 工作流程

将 API 视为业务目标的重要驱动因素是最近才出现的发展趋势，现在各公司已开始在其 API 战略上投入巨资。与此同时，API 描述格式（如 Swagger）的采用也呈爆炸式增长，这些格式有助于简化开发并推动组织 API 的采用。在我们即将举行的网络研讨会 API 经济以及如何优化您组织的 Swagger API 工作流程 中，我们将深入探讨组织应如何思考其 API 战略，以及像 Swagger 这样的 API 描述格式如何提供帮助。我们将提供为您的 API 生命周期建立工作流程的最佳实践，并向您介绍您的团队如何使用 SwaggerHub 来协作设计、记录和开发您的 API。涵盖的一些主题包括

  • 什么是 API 战略？
  • API 呈现哪些商业机会？
  • 成功的 API 战略有哪些要求？
  • 确定正确的 API 开发方法
  • 使用 SwaggerHub 优化 API 工作流程

网络研讨会将于美国东部时间 1 月 25 日星期三下午 1:00 举行。立即注册！

您可能也会喜欢