大规模分解API优先转换。在PayPal学习的经验教训–第2部分

本文是 Untangling an API-first Transformation at Scale. Lessons Learnt at PayPal – Part 2
的翻译,仅供学习交流。如有翻译不当,请斧正。所有权归原作者,侵删。

要点:

  • 为您的业务定义业务能力分类法
  • 在谈论和思考您的API时采用API产品心态
  • 开发以客户为中心的流程来管理您的API产品组合
  • 将服务实现工件与API分离
  • 您的API转换是一种文化变革,而不是一次性项目

这是一个由三部分组成的系列文章的第二部分,该系列文章探讨了PayPal如何采用更为API优先的方法来构建平台服务。在第一部分中,我们探讨了迁移到松散耦合,
API驱动的体系结构的原因,以及使该过程大规模运行所需的一些基础结构。在本文中,我们将仔细研究如何管理API本身的产品组合。

充分利用每一项API投资

您正在不断构建新功能。从理论上讲,这些投资中的每一项都是由正当,合理地战略和路线图驱动的。

现实更加混乱。我们倾向于将路线图视为优先投资的连续体,以帮助我们实现战略目标。但是,随着我们缩短时间范围,出现了一些实际情况。首先是我们的立即
执行计划往往因为一小部分高知名度项目和关键合作伙伴关系而严重影响。部分原因是希望有一些切实得目标可以团结起来,也可能是紧急项目需要先完成。
我们可能已经与一个大客户签订了重要协议。我们可能已经收购了一家需要整合的公司。这样的功能可能需要在假期之前推出。这些都是非常
真实的项目,具有非常真实的日期。事实证明,当实际上,我们漂亮得、战略上一致得、哲学上合理得路线图看起来更受事件驱动。

这有问题吗?好吧,没有,从使团队朝着共同目标努力并确保我们专注于业务最重要得优先事项的角度出发。它有助于调整组织。它在战术层面上提出的挑战是,
我们已经将精美得平台愿景缩减为一小组狭义的解决方案。底层工人(负责实际完成工作的人员)自然会为其成功进行优化。他们的环境成为当前的项目,
这意味着他们倾向于在这些解决方案范围内做出决策。

在API优先组织中,这是一个巨大的挑战。我们正在尝试构建一组可重用的功能,这些功能不会过度偏向任何特定的合作伙伴或项目。我们希望我们的技术投资能够
最大程度地发挥其效用,这意味着构建可在多种环境中使用的通用,可重用的API。我们不仅需要满足直接项目推动投资的需求,而且还要满足我们看不到的所有其他
项目的需求。然而,可以看出,我们路线图的狭窄,以项目为导向的成功标准滋生了张力,其最大目标是最大化平台服务效用。考虑到这些限制,我们如何防止在
服务设计中做出会限制我们未来业务敏捷性的狭窄近视决策?

识别您的业务能力

问题空间的定义对解决问题的思路有很大影响。确保您始终在构建平台功能,而只盯着如何解决明确定义组成业务的功能。这是你需要思考的。

业务功能代表您的业务为支持运行所需的业务流程所需的核心,可重用的构建块。通过定义业务能力分类法,您可以建立一种共享的语言,所有域都可以使用该语言来
描述任何给定流程中的逻辑关系。这是一个稳定的,业务驱动(而不是技术驱动)的环境,可以在其中讨论随着时间的推移保持相对一致的解决方案。
它还提供了企业如何看待其投资与技术如何利用它们之间的关键链接。

在小公司里,能力是非常有限的。在资源高度受限的情况下,你可能会构建一些让你的业务与众不同的核心服务,并利用其他服务提供商来做一些通用的事情,
比如消息传递、身份识别、支付等等。管理他们并不难,因为他们都是核心开发者。将它们写下来并明确定义仍然是非常有益的,但是管理它们可能由
一个首席架构师或一小群紧密联系的涉众来完成。很少需要正式的过程,或者一般忽略。

随着团队的发展,事情也会发生变化。如果你有数百个分散在多个业务部门和产品线的团队,跟踪你所拥有的并避免重复投资就会变得很困难。
为了解决这个问题,您需要一些模型或系统来跟踪和管理扩展组织中的 API 投资组合。这本身就是一件“事情”。

当我们开始在 PayPal 重建平台时,我们很清楚我们的目标是什么。我们花费了大部分时间来分解各种业务流程,以确定我们的核心业务能力。由于您永远不会
完全理解数千万行代码,所以它并不完美,但是遵循 8-2 规则,它为我们提供了一个很好的入门分类法,我们可以使用它来分类和管理将来要构建的 API 。
也许最重要的是,它给了我们一种描述最终状态边界的通用语言。我们利用这一点与领域所有者就他们正在构建的api和服务进行了建设性的、可讨论的
(而且基本上是一致得)对话。

这个简单得示例说明了我们如何定义功能并将其分配给组。这些组表示包含相关功能的高级域。注意,这是整个模型的一个非常简化的快照。

(https://res.infoq.com/articles/paypal-api-first-part2/en/resources/Picture-api.jpg

总共,我们确定了七个或八个高级域中的70多种业务功能。在过去的几年中,随着业务的发展,我们对模型进行了微调,并更好地了解了我们的各种业务流程,
但是原始模型始终是有用得基线。

这种做法对你在行业中寻找其他的例子是有帮助的。在我们的案例中,我们很大程度上依赖于为银行业开发的模型,因为我们有许多相同的行业概念。特别是
BIAN模型非常有帮助。在我们的业务扩展到传统银行业务之外的地方,我们利用其他行业的能力扩充了BIAN。
我们还必须发明一些独特的业务。这些特例很有趣,它们典型地代表了你所做的最差异化和防御性的投资[^1]。

在整个过程中,我们与公司的团队一起验证我们的假设,并得到他们的支持。领域架构师是关键贡献者,不过您必须小心,不要让当前的实现架构过度影响
业务架构定义。请记住,业务能力边界和语言应该由客户用例和支持它们所需的流程驱动。如果你的最终结果对组织之外的人没有意义,你可能需要重新审视它,
努力消除内部实施和组织偏见。这是一场持续的斗争。

向API产品观念转变

在定义业务能力边界时,不仅应该假定以客户为中心的观点,而且在定义实际 API 时也必须这样做。业界花了一段时间才明白这一点,但事实是 API 就是产品。
它们是给客户使用,解决问题的,所以它们必须很容易理解,而且使用体验要足够好。你甚至可以把其中的一些卖给客户,赚到真金白银。对于工程和产品领域的
许多人来说,这是一种新的想法。

原因很容易理解。API 的产生源于工程连接系统的需要和改进组件化的愿望。它们是“如何”的一部分,而且它们在当前项目之外的效用对许多人来说并不明显–
尤其是产品经理。还请记住,我们的短期路线图倾向于根据相对狭窄的项目结果来定义成功。将 API 设计决策偏向于直接的项目优化而不是通用得可重用性是一种
很自然得倾向——这通常需要更多的工作。在执行的压力和压力下,不清楚为什么你应该关心驱动你下一份薪水的外部环境。你必须在最后期限前完成任务。

在冲刺中,所有决定都是战术性的。

在 API 优先策略中,如果您设计接口良好,着眼于通用得可重用性,那么它们将成为构建块,在其之上构建未来的业务流程和产品。你今天的投资将来会有回报的。
因此,挑战在于克服对项目优化决策的偏见,并采用 API 产品思维。让我们看看鼓励这样做的一些属性和行为。

像客户一样说话

第一件事是从客户的角度开始谈论您的 API 。您确定的业务功能集是使用从外到内看对人有意义的语言定义的。内部概念、代码和首字母缩略词在API分类法或
描述它们的文档中没有位置。使用以客户为中心的语言有助于将概念性业务功能和相关api与底层物理实现解耦。它使您的 API 更容易被领域外的人理解和使用。
这是至关重要的。

第二步是认真对待 API 和资源的命名。这看起来很简单,但是在理解您的 API 投资组合时,名称是非常重要的。有时候,很容易忘记阅读和理解API的人。
而计算机只会按照您的要求进行操作-名称无关紧要。实际上,人是根据您提供的API词汇阅读,理解,概念化和综合解决方案。如果您选择一堆含糊或不直观的
资源名称,则会增加认知负担,并给开发人员客户增加生活的难度。集成的成本对于任何想要使用它们的人来说都是上升的。

管理您的API产品组合

如果您阅读了本系列的第一篇文章,您会注意到一个称为“标准(Alignment)”的步骤。你会在这一步确定底层 API ,这一步很关键。在此,您需要考虑API将支持
的通用用例,并选择最好得名词和动词来表示接口的资源和动作。

一个最佳实践是写下API要解决的用例。如果你强迫自己写出好的客户用例,你会从中发现你想要的资源和动作(Actions)的关键词。路径(endpoint)几乎是自己
写的。在更广泛得 API 组合环境中验证它的位置也变得容易得多。

挑战在于,大多数产品经理不参与 API 设计,而大多数开发人员也不从用例的角度考虑他们的 API 。开发人员倾向于从实现的角度来考虑问题。
如果你让一个开发人员写一个用例,他们通常会写出这样的东西:

我需要收集 region_2 数据插入表 legacyFoo 中,以便 oldService_B 可以返回决定。

这对领域之外的任何人都没有意义,而且很可能导致同样晦涩的 API 。相信我,我遇到逼着更烂的。退后一步并分析导致此需求的业务流程通常会揭示一个用例,
类似于以下内容:

作为消费者,我需要提供成功完成付款交易所需的所有地址信息。

这是正常人能理解的说法。它开始指向一个称为 “地址” 的潜在资源。回到我们的模型,我们还可以推断,地址可能与身份域内的帐户功相关。
现在可以很容易地查看该功能中的其他 API ,以确定这是一个新的资源,还是仅仅是对现有资源的扩展(或可能重复的功能,我们可以避免一起构建)。

得到一些过程(Get Some Process)

当提到“过程”这个词,人们反感。这是“乐趣”和“创意”的对立面。事实上,过程的存在很大程度上是为了实现结果的可伸缩性和结果的一致性。
虽然希望和梦想是很好的激励因素,但您需要一些切实得东西来确保您的 API 组合以某种合理的方式发展。挑战在于如何使开发过程快速、高效,
以及在开发人员客户眼中增加价值。如果你成功了,你就把这个“过程”变成了开发人员寻找的资产,使他们的生活更容易。这是衡量任何有价值的、
长期存在的流程成功与否的关键标准。

在PayPal的主要做法是要求所有 API 都经过一个共同的治理步骤。我们有一个小型的、中心的、很大程度上自治的团队,作为主要的 API 投资组合管理小组。
它由与每个业务能力领域的主要涉众和架构师合作的技术产品经理组成。他们与每个团队合作,帮助定义他们的通用用例,推荐最好的词汇表,并最终确定他们的
API 名称、资源和端点。

刚开始,这种模式遭到了许多抵制。这只是又一个阻碍我们完成工作的官僚主义步骤。开发人员倾向于等到最后一分钟(通常是在实现几乎完成之后)才参与进来。
这给双方都造成了很大的痛苦。随着时间的推移,人们的态度发生了转变。由于团队已经经历过几次,他们已经开始理解使用好得文档公开易于理解的接口的价值。
客户问题少了,他们的工作量也少了。

今天,我们看到团队在软件开发生命周期的早期就参与到 API 组合调整过程中。许多人在 SDLC 早期就主动寻求建议,因为他们看到了泛型化方法是如何使接口和
实现更简洁的。另外,客户视角和业务架构建模会影响他们对长期实现架构的思考。这有助于他们与业务保持一致。一些团队正在经历 API 和服务的第二次或
第三次迭代,因为他们正在朝着更清晰、更简单的模型发展,以帮助他们更容易地为所有客户服务。最重要的是,开发人员已经开始意识到不必自己解决所有这些问题。
他们看到了这个过程对解决眼前问题的价值,这鼓励了他们回来。

与您的客户交谈

当然,获得客户反馈,了解他们的需求并验证其满意度是良好产品管理的主要行为。当将API视为产品时,您的主要客户是开发人员。

这不是大多数人对API的看法。同样, API 开发通常由项目目标驱动,这是衡量成功的标准。 API 是达到目的的一种手段。我们如何改变行为方式,
以便真正考虑开发人员实际使用您的API的经验?

我们在PayPal采取了一些措施来鼓励这一点:

  • 在设计审查期间,我们鼓励 API 开发人员联系他们的客户,获取有关他们的设计反馈,并与他们合作以确保其文档透彻和易于理解。
  • 所有 API 合约均在著名的 Github 仓库中进行管理,鼓励每个人订阅,查看更改并提交请求请求。
  • API 门户包含指向团队松弛渠道的链接,因此客户可以轻松地获得帮助并提出问题。
  • 我们会将所有拉取请求发布到 Slack ,因此 API 客户可以更轻松地关注他们感兴趣的 API ,并在情况发生变化时得到通知。
  • 客户的建议,错误和问题可以通过 API 门户提交,并在包含 API 规范的同一 Github 存储库中自动进行跟踪。

所有这些工具都有帮助,但归根结底,API 开发人员必须有理由关心其客户的体验。激励措施必须统一起来,并被管理层视为重要。需要某种形式的工具来衡量
每个 API 开发人员在满足其客户期望方面做得如何。这是我们刚刚开始探索的一个领域,我们正在寻找其他方法来增强行为,从而提高 API 客户的满意度。同样,
这是一种文化变革,需要时间。它不一定存在于组织的 DNA 中,您将需要尝试各种方法来构建这种思想。

产品管理的作用

我们一直将 API 作为产品来讨论,但没有真正解决产品管理的角色。它很可能因组织的不同而不同。如果你有一个技术性很强的产品管理职能,
他们很可能会高度参与其中,并想在其中发挥主导作用。他们会从本质上了解通过领导这次对话可以带来的需要和价值。这样,API产品组合管理就变成了一个跨
所有领域的联合体,而产品是一个高度参与的利益相关者。如果你就是这样的人,那么你应该感到幸运。

如果你没有一个固有的技术产品管理团队,那么组建一个中央团队来扮演这个角色并提供跨平台的一致性可能是唯一实际的、短期的解决方案。这在很大程度上取决于
组织的动态、文化和成熟度级别。随着时间的推移,当您加强您的产品组的技术技能集(并调整激励措施)时,您可能还能够朝着更加分散的模型发展。
我们也看到一些领域有非常积极得产品经理参与其中,所以混合的方法可能也是合适的。您需要确定组织中产品经理的实际参与程度,并针对具体情况定制方法。

逻辑与物理解耦

当我们讨论 API 时,我们讨论的是服务交互应该如何行为的逻辑定义。实现API的服务是实际的、被部署和服务请求的物理工件。很容易假设它们之间的关系总是1:1。
你应该质疑这个假设。

我们发现这种关系可以是很多的。这有几个原因:

  • 在逐步使用新 API 服务取代相同契约的老服务的过程中,会有一段重叠期,其中一些接口(endpoint)由遗留服务提供服务,而另一些接口由新服务提供服务。
    其优点是可以在每个版本中替换遗留服务的一小部分,并且可以减轻替换大型复杂服务的风险。
  • 两个 API 之间存在大量实现重叠,并且开发人员希望通过同一服务为这两个 API 提供服务,以节省时间和开发工作。
  • API的读写活动完全不平衡,架构解决方案是将读写分为单独的服务。
  • 有许多糟糕的、没有长远考虑的或组织结构驱动的架构决策可能导致 1:1 比例之外的结果。基本上,糟糕的设计或日期驱动的决策有时会损害完全封装、
    良好绑定的服务到 API 关系的目标。

一个明显的含义是,您可能应该将 API 规范维护在与实现代码不同的存储库中。这使您可以轻松地将 API 与服务的关系以及生命周期解耦。事实证明,
API 生命周期由您的 API 版本控制和向后兼容策略决定。服务的生命周期可能由正交的问题驱动,例如错误修复和对操作质量(如性能和可用性)的改进。
只要始终遵守 API 合同本身,去耦就可以使每个人独立发展。

解耦还强化了API约定本身就是一等公民的概念。它应该驱动实现(API优先),而不是反过来。当维护每个工件的过程中有明确的分离时,这种角色转换更容易加强。

在处理过程中,控制问题很重要。在 PayPal ,我们对谁可以合并 API 存储库中的更改保持非常严格的控制。每项变更均与投资组合保持一致,
并根据标准进行评估以产生成熟度分数。集中团队开始完成大部分工作。随着我们的成熟,我们已经培训和委托了整个组织中的开发人员以更加联合的方式进行操作
(在下一篇文章中有更多介绍)。即便如此,我们仍努力避免开发人员合并自己的更改,并鼓励尽可能多得跨域协作和审查。

最后,人们一直在与康韦定律斗争。

设计系统的组织…是否被限制生产复制这些组织的通信结构的设计
(organizations which design systems … are constrained to produce designs which are copies of the communication
structures of these organizations)

– 康威

开发人员在团队中找到价值。在重组后,团队喜欢做的第一件事就是创建一个以其团队命名的新服务——slicedbreadserv。该项目代表了他们未来的
工作以及对组织的贡献。稳定、长期有效的 API 是我们的目标。就像任何产品一样,删除的代价很高。比较,重组经常发生,并且通常是由非常不同的力量驱动的。
将 API 平台产品的定义与底层实现更改的想法分离开来是好的。你可以试着控制其中一个。另一个你肯定不能。

This is a Lifestyle

我们在开发 API 组合管理学科的过程中,学到了很多东西。将思维和行为转变为更以客户为中心、API产品驱动的方法是可行的。有时这很痛苦,
出力不讨好,困难重重,但通过倾听和接受双方开发人员的需求,我们设法不断完善程序并提高内部客户满意度。

有一句经常被重复的谚语:开发人员是懒惰的。我们不相信。当有有趣的问题需要解决时,开发人员会努力工作。他们渴望知识和技能,使他们能够更快、
更优雅地解决问题。最重要的是,他们不想把同一个问题解决两次。

API产品的承诺之一,设计第一的系统设计方法是你可以同时为更多得人解决同样的问题。它令人着迷且优雅。理解需要时间,但一旦理解,就会产生强大的力量。
我们实现的方法和过程帮助我们引导组织沿着这条道路前进。你永远不会真正达到目标,但是从文化变化的角度而不是从项目的角度来处理问题,影响深远的。

在最后一篇文章中,我们将探讨计划管理对调整组织,推销概念,提供培训以及创建各种鼓励采用的激励机制的重要性。

关于作者

Erik Hogan近二十年来一直在学习成为一名出色的产品经理意味着什么。大部分时间都花在了了解如何成为可以扩展的客户拥护者和可信赖的领导者上。
他非常满意,可以将复杂得问题分解为可重复使用的部分,并为工程提供准确执行快速执行所需的功能。最近,他一直在使用简单性,
讲故事和专注等基本产品概念来影响组织变革,这是一种非常不同的“产品”。同样,当他的妻子要求她的成功标准时,他仍然生气。

[^1]: 大概想表达一种独属于你的特色, 也是你区别其他同行产品的竞争力。
[^2]: 直译是在这一步,你可以确定 API 在更广泛的功能组合中所处的位置。