第一章 API管理的挑战
管理首先是一种艺术,科学和技术交汇后的实践.
Coleman Parkes在2017年发布了一项调查,它显示10家全球企业中近9成有自己的API程序.调查同时也显示了这些企业从它们的API程序中看到了各样的好处.包括平均18%的市场增速.然而,只有大约50%的企业说自己有先进的API管理程序.这指出了一个存在于许多企业级API程序中的关键问题:核心盈利的可操作API和支持盈利API的管理技术和基础设施存在差异.这也正是本书想解决的问题.
好消息是许多企业有了自己成功的API程序管理经验.不太好的是它们的经验和特长不易于分享和推广.原因如下:大多数情况下,有良好API管理程序的组织因业务繁忙,无法分享自己的经验.少数情况下,我们了解到一些企业对API管理特长的分享很谨慎,他们确认API技术是一个竞争优势,并有意降低它的开放性.最后,即使企业对大家分享了他们的经验,这些信息通常也是企业内部可用或者难以转换成通用的机构API程序.
本书试图去解决最后一个问题--将企业内部可用示例转换为通用经验.为此,我们访问了数十家公司,采访了许多API技术专家,并试图找到公司已经分享的示例之间的共同点.有一小部分主题贯穿本书,我们将在这里分享这个介绍性章节。
要认识API,一个关键点是弄清人们所说的API是什么.首先,术语"API"可以指接口(如:HTTP请求URL,JSON响应).它也可以引用需要在生产环境中放置可访问服务的代码和部署元素.最后,我们有时使用API去引用一个正在运行的API实例(如:运行在AWS云或者Azure云上的第三方API).
管理API的另一个重要挑战是设计、构建和发布单个API和支持,管理多API（我们称之为API景观）之间的差异.我们在这本书里花了大量的时间处理这两个方面.像API即产品概念和需要被创建,维持API的技术(API核心)是处理单API挑战的例子.我们还讨论API成熟度模型的作用和将处理时间变化的工作作为管理API的重要方面.
另一个方面是管理API景观.你的景观是涵括了你的公司中所有业务域的,运行在所有平台的,被所有API团队管理的的API.这种景观的挑战有几个方面:包括规模和范围是如何改变API的设计和实现,以及大生态系统是如何因为大小而产生波动性和脆弱性.
最后,我们谈谈在管理API生态系统时的决策过程.根据我们的经验,这是为你的API程序创建一个成功的管理计划的关键.事实证明,你做出决策的方式需要根据你的景观变化而变化.保持旧的管理模型会限制你的API程序的成功,甚至会向已存在的API中引入更多的风险.
在我们深入讨论如何学习处理这两个挑战(单API和API景观)的细节之前,让我们先看看这两个重要的问题:什么是API管理?为什么它这么难搞?
API管理是什么?
如前所述,API管理不仅仅涉及管理API的设计,实现和发布,还包括API生态系统的管理,组织内的决策分配,甚至包括迁移已有API到不断增长的API景观中的过程.在本节中,我们将花时间讨论以上每一个概念.但是首先,先简单解释一下我们所说的"API"是什么意思.
- API是什么? 有时当人们使用术语"API"时,他们不仅谈论接口,而且还谈论功能(接口后的代码).如,一些人可能会说:"我们需要尽快发布已更新的客户API,这样其他团队可以使用我们已实现的新的查询功能".有时,人们可能用API仅仅去引用接口的细节.如,你的团队有人会说:"我想为已存在的支持我们客户管理工作流的SOAP服务设计一个新的JSON API".这两种说法都对,而且他们似乎很清楚这两种情况的含义,但是有时它们会让人困惑.
为了明确区别,使我们更容易的讨论接口和功能,我们将介绍一些额外的术语:接口,实现,实例.
接口,实现,实例 API是应用程序编程接口的缩写.我们使用接口来访问API后面的东西.如:你可能有一个API来公开管理用户的任务.这个接口可能允许开发人员去:
- 创建新账户.
- 编辑已存在账户的配置文件.
- 改变账户状态(激活或停用). 这个接口通常的表现形式是使用HTTP,Thrift,TCP/IP等共享协议,并且依赖于像JSON,XML或HTML之类的标准格式.
但这知识接口.有时它需要去执行请求任务.我们把其他的东西成为实现.实现是提供实际功能的部分.这些实现经常被像JAVA,C#,Ruby,Python等编程语言书写.继续以用户账户为例,一个用户管理实现可以包含创建,添加,编辑和移除用户的能力.这个功能可以通过上面提及的接口进行对外暴露.
接口与实现的解耦 注意,所描述的功能实现是一组使用创建,读取,更新,删除模式的简单操作.但我们描述的接口有三个操作:新建账户,编辑账户,改变账户状态.实现和接口之间的不匹配似乎很常见而且可以被扩大.它将每一个服务的的具体实现与访问服务的接口解耦,使它更易于随着时间而不中断的改变.
我们的列表中第三个术语是实例.一个API实例是接口和实现的组合.这是讨论已经发布到生产中的实际运行API的简单方法.我们使用一些指标去管理实例已确保他们的健康.我们注册和记录实例,以便于开发人员通过查找和使用API去解决实际问题.并且我们确保实例的安全,以确保只有认证后的用户可以执行这些操作和读写操作所需的数据;
图1-1阐明了这三个元素的关系.通常在本书中,"API"指的是API实例:一个接口和实现的完全操作组合.只有我们想突出接口或者实现时,我们才会在文中声明它.
这些实践领域的好消息是它们超越任何单API.如:记录API技术可以很好的从一个API团队迁移到下一个API团队.学习适当的测试技术,安全模式等也是如此.这也意味着即使每一个单独的团队(销售团队,产品团队,后台团队等)都有自己的API域,你依旧有"交叉"的点可以绑定不同团队的人(在音乐流媒体Spotify中,他们称这些交叉组织为"工会".参考"扩大你的团队"获取更多信息).这也是管理API的另一个重要的方面--支持和设计构建它们的团队.我们将在第七章讨论它们如何在不同的组织中工作.
- API成熟期 了解和理解API核心并不是这个图片的全部.你程序中的每个API都有自己的"生命周期"--一系列可预测的和有用的阶段.了解你的API所处阶段可以帮助你确定当前API需要投入的时间和资源.理解API是如何成熟的有助于你识别各种API相同的阶段,帮助你准备和响应每个阶段不同的时间和能源需求.
表面上,在设计,构建和发布API时处理所有API核心是有意义的.但事实却相反.在API早期时,更多关注的是设计和构建方面,减少记录方面的工作.如:在其他阶段(验收测试人员获取到原型)花费更多的时间在监控API的使用和保护它不备滥用更重要.理解成熟阶段将帮你最大限度的分配有限的资源.我们将在第六章让你们了解这个过程.
- 不止一个API 许多读者可能已经知道,当你开始管理大量的API时,情况就会发生改变.随着时间的推移,我们的客户需要构建,监控和管理数千个API.在这种情况下,你将更少的关注单个API的实现细节,而是更多的关注在不断增长的动态系统中如何保持这些API的和平共处.正如前面提到的,我们将这个生态系统称为API景观,在本书的后半部分中,我们将花几个章节介绍这个概念.
这里的大部分挑战是如何确保一定程度的一致性,不会因为集中化管理和检查所有API细节而造成瓶颈和降速.这一般通过向各个API团队扩展这些细节的责任,将核心管理和统治致力于API间交互方式的标准化,确保存在一组核心共享服务或者基础设施(安全,监控等)对于所有API团队是可用的,并且通常为更自主的团队提供指导和训练.也就是说,远离通常的集中式命令控制模型是必要的.
另一个挑战是:当企业的工作向着分散决策和深度自治时,企业的高层很容易对发生在团队级别的重要活动失去可见性.然而在过去,一个团队可能必须获取许可才能去做,企业只赋予指定团队自治权,以鼓励他们采取行动,而不用等待上级审查和许可.
管理API景观的大部分挑战都与规模和范围有关.事实证明,随着你的API程序的增长,它不仅仅是变大,而且还会改变形状.我们将在本章后面更详细的讨论这个问题(参考:"为什么API管理困难?").
- API的业务 除了API的创建和在API景观中管理他们之外,重要的是谨记:所以的工作为了支持业务目标和目的.API不仅仅是JSON,XML,同步,异步等技术细节.它们是联系业务的纽带,帮助公司以有效的方式公开重要的功能和知识.API通常是一种解锁组织中已有价值的方法.如:通过创建新应用,启用新的收入流和初始化新业务.
这是更多的关注API消费者的需求而不是生产和发布API的理念.以消费者为中心的方法通常被称为"待完成工作(JTBD)".它由哈佛商学院的克莱顿·克里斯藤森提出,他的著作<创新者的困境和创新者的解决方案>(哈佛商业评论出版社)深入的探讨了这种方法的力量.为了启动和管理一个成功的API程序,它明确的提醒着API的存在是为了解决业务问题.根据我们的经验,善于将API应用于解决业务问题的公司,会将其API作为"完成工作"的产品.就像克里斯藤森的JTBD框架解决消费者问题一样.
API程序可以帮助企业的一种方式是通过创建一套灵活的工具集低成本的构建新的解决方案.如:如果你有一个在线销售API,它允许核心伙伴去管理和追踪他们的销售活动;一个市场促销API,它允许市场团队去设计和追踪产品促销活动;那么你就有机会创建一个新的解决方案:销售促销追踪应用.
API可以帮助企业的另一个方式是使访问重要客户或者市场数据更容易,以关联得出新客户出现的趋势和特定行为.通过安全易用(适当的匿名和过滤)的数据,API可以是你的企业发现新机会,实现新产品/服务,甚至以更低的成本和更快的时间去开启新计划.
我们将在第三章涉及API即产品这个重要方面.
- 为什么API管理如此困难? 正如我们在本章开始时所说的,当大多数企业已经启用API程序时,只有50%的企业考虑如何做好API的管理工作.这里发生了什么?有什么挑战?你又该如何帮助公司克服它们?
当采访了全球的企业后,我们对于API生命周期管理得出了一些基本主题:
范围
当管理API时,核心软件架构团队应该关注些什么?
规模
通常,当公司刚开始他们的API之旅时,有效的东西并不会随着团队的规模而扩展;
标准
我们发现,随着程序的成熟,管理和治理工作的重心需要从API设计和实现的细节移到API景观的标准化上,使团队在细节上更自由地做出他们的决定;
本质上,范围,规模和标准这三要素促进了API管理程序的健康发展.由于这个原因,它值得我们深入研究一下.
- 范围 运营一个健康的API管理程序的一大挑战是实现适当的中央控制水平.而且,为了其更具挑战性,这个适当级别还要随着程序的成熟而改变;
在项目初期,直接关注API设计的细节是有意义的.在构建API的初期,这些设计细节可能直接来源于API的创建团队,他们看重现实中已存在的项目,采纳对计划创建的API样式有意义的工具和库,并实施与实现该API.
API程序在早期状态时,所有东西都是新的;所有出现和解决的问题也是第一次遇到.这些初始经验经常被记录为公司的"API最佳实现"或者公司指南等.对于一个小团队来说,首次开发一些API是有意义的.然而,这些最初的指南可能是不完整的.
随着公司中API团队人数的增加,对于API的风格,经验和观点也随之增加;这时很难维护API的全局一致性,这不仅仅是因为一些团队没有坚持公司指南,还因为一些团队正在与不同的现成产品集合作,这些产品限制了他们遵循原始的指南.也许他们在事件流中不起作用,并且支持以XML为基础的访问和响应API.当然,它们需要指导,但是这需要符合他们的领域和客户的需求.
一些指南确实需要所有团队去共享,除此之外这些指南还需要去匹配他们的问题域和客户需求.随着社区的发展,多样性会增加,而且重要的是你不要错误的去消除这些多样性.这正是你的控制能力需要从发出指令(如:所有API必须使用下面的URL模式...)转换为给出指导(如:运行在HTTP上的API应该使用下面的URL模式..)的地方.
换句话说:随着程序范围的扩张,你的指南集也需要适当的扩展.这对于全球企业来说尤其重要,因为地方文化,语言和历史在团队的思考,创造和解决问题方面发挥着重要的角色.
同时这也引导我们进入到了下一个核心元素:规模
- 规模 创建和维护一个健康API管理程序的另一个大挑战是处理规模随时间的变化.正如我们在上一节讨论的,团队人数增加和他们创建的API数量可能成为一个挑战.在运行时监视和管理API所需的过程也将随着系统的成熟而变化.因为单团队在单区域使用的对少数API的全部构建的追踪工具和追踪跨越多时区和国家的成百上千的API终端的工具有很大不同.
在这本书中,我们将API管理方面称为"景观".随着你的程序规模的增加,你需要关注多地,多团队的多过程.你将更依赖监控运行行为,以了解你的系统在任何时的健康情况.在本书的第二部分(从第8章开始)我们将探讨如何管理API景观,可以帮你指出哪些元素值得你关注,哪些工具和流程可以帮你掌握不断增长的API平台.
API景观构成了一系列的挑战.当你需要扩展API生态系统时,你用于设计,实现和维持的单API流程不总是相同.这基本是一个数字游戏:你系统中拥有的API越多,它们之间的交互也越多,它们之间发生未知行为(或者说错误)也就越多.这就是大型系统的工作方式--交互越多,错误越多.尝试去消除这些错误也仅仅是延续API使用,因为并不能根除所有漏洞.
这就导致了API程序所面临的第三大挑战:如何在你的API程序中应用适当的标准去减少意外的变化?
- 标准 当你将管理等级从API级别提高到景观级别时,一个关键的转变是:标准化会为你的团队设计,实现和部署API提供一致性的指导.
随着团队的增长(包括负责机构API的团队),相互之间的沟通成本会增加(参考"决策").不断增长的规模需要改变范围.解决这个挑战的关键方法是采纳通用标准而不是特定的设计约束.
例如:万维网(World Wide Web)自1990年创立以来能够一直良好运行的原因之一是:它的设计者很早就决定依赖于适用于所有类型的软件平台和语言的通用标准,而不是创建基于任何单语言或框架的具体实现的指导.这就允许创新团队在不破坏现有实现的基础上去开发新语言,架构模型,甚至运行时框架.
帮助万维网持续成功的长寿标准的共同点是关注组件和系统交互的标准化.不同于在内部标准化组件的方式,万维网的标准化是致力于网络间的组件可以更容易的相互理解.同样,随着你的API程序成熟度的提高,你提供给API社区的指导方针需要更关注通用交互标准而不是特有实现细节.
这可能是一个艰难的过渡,但这是获取健康API景观必须走的路.只有这样你的团队才有可能去构建让已有的和未来的API之间更容易进行交互的API.
- 管理API景观 如本章开头所述,API管理空间中存在两个关键挑战:管理单API的生命周期和管理所有API景观.根据我们对于API管理的研究和观察,发现了许多"管理单API"版本的故事.它们关于"生命周期"和"成熟模型"的记录为识别和降低设计,构建和部署API的挑战提供了切实可行的建议.但是它们并没有太多对于API生态系统(这里称为"景观")的指导.
景观也有它自己的挑战:它自己的行为和倾向.当你设计单API时需要考虑与你要支持十个,百个甚至千个API所要考虑的内容并不相同.在生态系统中的规模是新的挑战,这些是不会发生在单实例或API实现上的.我们将在后面深入研究API景观,但是我们想在本书的开头指出三种方式,根据API景观对API管理呈现出的独特挑战:
- 缩放技术
- 缩放团队
- 尺度治理
- 技术 当你开始第一次启动你的API程序时,需要你做出一系列会影响所有API的技术决策.实际上,所谓的"所有"API只是一个小的集合这一点并不重要.关键是,当你构建你的初始API程序时,你可以依赖一套稳定的工具和技术.当我们深入到API生命周期(第六章)和API成熟度的细节时,我们将看到API程序不再便宜,并且你需要谨慎的控制你在活动中的时间和精力投入,因为这会对你的API成功产生很大影响,同时在这个过程的早期又不会冒很多资本风险.这通常意味着选择和支持一小部分工具和提供一个十分清晰和详细的技术指南,去帮助你的API团队去设计和构建既能解决你的业务问题又能很好地协同工作的API.换句话说,你可以通过约束技术范围去获取早期的胜利.
由于我们提到的所有原因,在刚开始时API运行会很好.然而,随着你的程序体积的增加和范围扩大(如:更多的团队构建更多的API在更多的地方服务更多的业务领域等),挑战也会改变.随着你的API程序的发展,依靠限制工具和技术集是降低API变化速度的关键因素之一.在一开始,当你有一个小团队时,限制选择可以让你做事更快;成本和风险高的企业需要限制团队的规模.如果你开始添加地理位置远的团队并且(或者)你开始并入新业务单元或者要求新公司加入你的API景观,这是非常正确的方式.多样性(参见"多样性")成为生态系统非常重要的成功驱动力.
因此,API景观管理技术一个重要部分是确定景观规模何时应当增加技术的多样性而不是一味限制.这么做,一部分和现实情况有关.如果API景观需要支持组织现有的基于TCP/IP的SOAP(简单对象访问协议)服务,则不能要求所有服务使用相同的URL指导规则去创建基于HTTP的CRUD(增删改查)API.创建新的Anguler事件驱动实现服务或者遗留的远程调用(RPC)实现也是如此.
在你的API景观中,更广的范围意味着技术的多样性.
- 团队 技术并不是API管理的唯一影响因素.随着程序的发展,API管理将面临一系列新的挑战.团队的结构也需要随着API景观进行改变.同样,在API程序的开始时,你只需要几个专心的人就可以进行操作,他们大部分人都从事所有工作.这也就是你听说的"全栈开发"或者"MEAN(MongoDB,Express.js,Angular.js,Node.js)"开发或者关于单个开发人员具有API程序所有方面技能的其他版本.你也许会听到很多关于"创业团队"或者"自给自足团队"的谈论.归根到底,你需要一个拥有全部技能的团队.
这种情况适用于你的API较少,同时它们设计和实现都使用相同的工具集(见"技术").但是随着API程序规模和范围的增加,你构建和维护API所要求的技术数量也会显著.你不能再期望每一个API团队都由一群拥有设计,数据库,后端,前端,测试和部署技能的人组成.你可能有一个团队负责设计和构建供其他团队使用的数据中心监控接口.例如,他们的技术可能需要覆盖用于收集数据的所有的数据格式和工具.或者你可能有一个团队,他们的主要工作是使用像GraphQL这样的单一技术或者其他查询中心库去构建手机应用.随着技术多样性的增加,你的团队可能需要变的更专业化.我们将在稍后的第七章探索它们的细节.
随着API景观的发展,团队需要改变的另一种方式是他们日常参与决策的方式.当你有一个小而且经验不太充足的团队时,将决策集中到一个单独的指导组是有意义的.在大组织中,这通常是企业架构组或者其他相似的名称.随着你的生态系统变的不均匀,范围的扩大,决策工作集中在较小的规模和范围将成为一个大问题.随着技术的进一步深入,单团队不可能保持跟进每一个工具和框架的细节.同时,当你添加越来越多的团队,决策本身也需要被分配;在一个全球化企业中,一个中央委员会很少能了解日常操作的实际情况.
解决方案是将决策过程分解为我们所谓的决策元素(见"决策的元素"),并将这些元素分配到公司内的适当级别.不断增长的生态系统意味着团队需要在技术层面变的更专业化,在决策制定侧面更加尽责.
- 治理 关于API景观的挑战,我们要谈的最后的领域是治理API程序的通用方法.同样,正如这里提到的其他情形,我们观察到治理的角色和级别将随着生态系统的增长而变化.新挑战的出现,旧方法不再像曾经那么有效.事实上,尤其在企业级别,坚持旧治理模型会减缓甚至阻碍API的成功.
正如在任何领导范围一样,当规模和范围受到限制后,提供直接指导的方法可能是最有效的.这不仅对小团队有效,而且对新团队也是如此.当没有太多操作经验,最快的成功方法是用详细的指导和过程文档的方式提供这些经验.例如:我们发现早期API程序治理经常采用多页过程文档去解释特定任务:如何为API设计URL,哪些名称对URL是有效的或者在HTTP头中版本号必须出现在哪里.提供清晰的指导方针且没有太多的可选项使开发很难偏离指定的API实现的方式.
但是,随着程序的进一步增长,随着添加更多的团队,支持更多的业务领域,社区惊人的大小和范围开始使得维护应用于所有团队的单一指导文档变的非常困难.正如我们在"技术"中提到的,剥离编写和维护应用于整个企业的具体过程文档的工作,通常不是一个好主意.技术的多样性在大型生态系统中成为一种力量,在企业治理中尝试去驾驭它可以减缓程序的增长.
这就是为什么随着API景观的扩展,你的治理文档需要从提供直接过程指令转变为提供通用原则.例如,与其写出构成公司有效URL的细节,不如将开发指向国际互联网工程任务组(Internet Engineering Task Force)在URI设计和主体标准(RFC 7320)上的指南,同时提供如何在组织中应用这些公共标准的通用指南.在大多数用户界面/用户体验(UI/UX)指南中可以找到这种指导原则的另一个很好的例子,如Nielsen Norman集团的"用户界面设计的10种可用性启发".这种类型的文档为UI模型的取舍提供了许多选项和理论.他们为开发和设计师在为什么和当什么时候使用哪些提供了指导,而不是简单的为他们设置遵守的要求.
最后,对于超大组织,特别是运营多地点和时区的公司,治理需要从发布原则转移到收集建议.这基本上是颠覆了典型的中央治理模型.中央治理委员会的主要角色不是告诉团队做什么,而是收集实际经验,找到它们相互之间的关系,在更广泛的组织内推广"最佳实践"的后端指导.
因此,随着API景观的增长,API治理模型需要从提供直接建议转为提出通用原则,再到收集和分享公司内团队的实践经验.正如我们第二章中将看到的,在那里你可以利用一些原则和实践,去创建适合你公司的治理模型.
- 总结 在这个开篇章节中,我们接触到了本书中出现的API管理的一些重要方面.我们确认,尽管API仍然是一种驱动力,但是接受调查的公司中只有50%自信他们有能力去正确的管理API.我们还阐述了术语"API"的许多用法,以及这些不同的用法如何使你的程序很难提供一致的治理模型.
最重要的是,我们介绍了管理"单一API"和管理"API景观"是非常不同的概念.在第一种情况下,你可以依赖API即产品,API生命周期和API成熟度模型.API的变更管理也非常关注这种"单一API"的思维方式.但这只是故事的一部分.
接下来,我们讨论了管理API景观--组织内的整个API生态系统.管理不断增长的API景观需要不同的技术和指标集:处理多样性,数量,波动性,脆弱性和几个其他方面的技术.实际上,这些API景观方面全部影响API的生命周期,并且我们将在本书的后面详细的介绍它们.
最后,我们指出:即使你对API程序做出的决策方式也需要随着时间而改变.随着系统的增长,你需要像分配IT元素(如数据存储,计算能力,安全和公司基础设施其他部分)一样分配决策的制定.
以这个介绍为背景,让我们首先关注治理的概念,以及如何使用决策和将决策分配作为整个API管理方法中的主要元素.