组织在弃用API时需要了解的事项

  2017年1月11日

在API领域,一个经常出现的话题是公司决定弃用API版本,或完全停止对热门API的支持。 以谷歌最近的例子为例,该公司于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框架支持操作的deprecated(弃用)标签,该标签将更新交互式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经济以及如何优化组织的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举行。 立即注册!

© . All rights reserved.