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

发表于 阅读次数：

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

要点:

  • 在大型组织中实现以 API 优先的转换既是技术难题，也是人员问题。
  • 组织架构将极大地影响您的API优先成功策略
  • 将转型本身视为产品可促进长期成功
  • 流程和治理是必要的，但要轻量并使其适合您的客户
  • 要低估对工具，基础架构和使其有效运行所需的人员的投资

制定API策略

过不了多久，对外公开您的核心系统就会成为僵局。真正的产品是基于这些内部内容构建的应用程序和体验。大多数产品投资都导致了垂直集成的解决方案，这些解决
方案只能提供相对有限的功能。投资一个完全不同得用例集或者不同得产品线通常是计较困难或不可行的。在这种情况下，很自然得就将基础架构视为浸没成本[^1]或
仅为内部系统。很难以不同得方式思考它。

大人，时代变了。现在每家公司或多或少的都有一个 API 策略，该策略通过以可重用服务的形式公开结果，努力利用其很大一部分技术投资。高级别目标是通过使
核心业务功能易于访问和可重用来加速业务敏捷性。降低集成成本不仅对内部速度产生积极影响，而且还挺提高了结合客户、合作伙伴和收购对象的灵活性与速度。整体
式，垂直排列的一团烂泥的时代快要结束了。现在统称为 “微服务”，他是通过精心设计和记录 API 公开的，且有清晰的有限上线文和语义上不同的业务价值。

API 经济

为什么要改变？ API 经济的出现改变了规则。

世界上一些价值最高的公司 Facebook 、Google 、Amazon 前不就都发现打开和服[^2] 并为外部开发人员提供更多的核心产品的访问权是利用其技术投资的好
方法，加强产品组合，扩大合作机会。他们建立了强化共享和重复使用原则的文化，这对于实现这一目标至关正要。这促进了 API 的经济发展，使许多新产品的构建
和市场测试比以前更快、更便宜。 API 提供商从以下方面收益：更多的客户、更多的流量、更深的集成，以及至少对于某些人而言，是数十亿美元新业务的开始。
甚至 Twitter 都将其早起的成功归功于 API 策略，即使以后他们撤回了。

第二梯队，像 Twilio 和 Stripe 这样的公司，完全跳过了传统的 “产品” 部分。他们将 API 本身作为其核心产品，并专注于提供出色的开发人员体验，以此
作为其首要任务。他们的客户迅速集成，并从基本必须的功能中收益，而不必自己构建和维护许多不可区分的功能。敏捷度提高。黑客马拉松开始了。应用和初创企业
爆炸式增长。它成为构建新体验，迭代和验证产品与市场的契合度的默认方法。

为了保持竞争优势，您的组织还需要采用 API 优先的方法。在您如何看待和思考您的技术产品组合方面将产生重大改变。

实现您的未来

对于较新的公司来说，他们可能已经像第二梯队那样做了。但是如果您是一家拥有大量现有基础设施和客户的大、成熟公司，该怎么办？在继续经营业务的同时如何进行过度？

首先，您的技术前景可能看起来完全不同。你的遗留代码库（可能受 SOA 影响，但在 “微服务” 还没成为一个词之前就已经开发了）可能不太理想。这些年来，您
可能积累了很多技术债务，并且您可能没有一种文化来固有地清华清晰得组件化和重用原则。测试可能参差不齐，各种重组和废弃醒目可能遗留下来的骨架。文档可能
有很多不足之处。这不是一个开始进行重大微服务转换的良好水平的基础。正如我们所说，存在许多 “挑战” 。

另一个主要的考虑因素是组织的变化。高管人员可能会相信 API 优先策略的必要性，但他们对实现该战略所需要的承诺的理解可能有所不同。了解自己在这个范围内的位置对你的成功非常重要。

极端情况下，你开始了一个新项目，所有进度停止，当务之急是所有人都完全参与这个项目，其他工作都要搁置。这种情况非常少见。如果您现在处于这种情况，直接
开干。把它看做一个庞大的项目，并快速实施。但您想再这么做几乎不可能了。

实际上您可能在两者之间。可能会承诺降低开发速度，但是走的会更远，并且在未来需要更新技术。作为转型的领导者，这感觉更加混乱。这其中有许多困难和重要的
问题，而这些问题没有明显的答案。如何确定优先级？那些团队会这样做？如何进行协调？什么时候做？您的工作变得更加复杂。它不在是一个项目。现在他是一个复杂
的转型，可能会持续数年，并且与祖师变革和技术变革一样重要。

给你的产品带上帽子(Put on Your Product Hat)

在 PayPal，我们已经实施了三年以上。我们采用一种以客户为中心的方法，从一个非常单一的、孤立得体系结构过渡到一组松耦合的 150 多种服务，他们具有精心
设计的现代 API 。

有一种将此过程视为工程醒目的趋势。我们没有。相反，我们将其视为更大得组织变更问题，而“产品”是我们设计和构建 API 的根本转变。因此，我们被迫确定和
服务所有关键的“客户”，即构建和使用 API 的开发人员以及支持它们的执行人员。它们决定了我们的战略，我们建立的工具，沟通方式以及衡量成功的方式。
识别客户并关注他们的满意度是一项基本的原则。这种心态使我们成功的关键，并且它将继续形象我们今天如何管理该计划。

虽然没有两家公司是相同的，但我们学到的许多经验教训和使用的方法都是用于同一条道路上的其他组织。

为了解决这个问题，我们使用成为 “3P” 的框架组织工作。

  • 产品 - 用于管理 API 和基础服务实现组合的基础结构，标准和工具
  • 产品组合 - 业务功能的目录，表示为 API 和基础服务
  • 计划 - 用于激励祖师行为和技术投资变化的指标，培训和杠杆

本文是这三部分的第一篇，后面将会更详细的阐述这些方面。

产品

在一个由几十到大约 50 或 60 个开发人员组成的小公司中，核心利息相关者进入会议室，在白板上定制计划，分担责任并开始工作并不困难。将计划和目标达成共识，
并且在进行一些迭代和过程更正后，您可能最后会得到一组很好得集成且紧密结合的 API 和代表平台的基础服务。您的时间轴可能以月为单位，或者以季度为单位。

在大型组织中，情况有所不同。您可能有成千上万的开发人员分布在多个业务部门和地区，所有这些业务都有不同的目标，而且通常具有不同的技术栈。由于许多原因，
其中最重要的 Dunbar的数字 您无法和每个人沟通，达成共识并开始工作。你需要的是一种更
分散、弹性的东西，这种东西能增强你的目标，而不依赖于脆弱的共识或大规模的项目协调。在这种情况下，“产品”实际是个是支持转换的基础（而不是 API本身）。
这本身就是一项重大投资。至少，它可能包括以下内容：

  • 定义 API 通用原则和标准的文档
  • 开发 API 时要确保良好的开发规范
  • 包含清晰可观的衡量方法在内的治理方法
  • 某种集中式门户网站，用于合并 API 以及管理流程和指标

原则于标准

在 PayPal ， 我们开始思考那些共同思想指导我们朝着现实良好封装服务的目标迈进，这些服务公开了设计良好、可重复使用的 API 。这些成为了我们的核心原则，
并构成了我们随后的标准文档。

  • 松耦合: 服务和消费者必须相互松散耦合
  • 封装: 域服务只能通过其他服务契约[^3]访问它不拥有的数据和功能。
  • 稳定性: 服务契约[^3]必须具有可测试的生命周期，并且使用寿命长
  • 可重用行: 服务必须开发为可在多个上下文中和由多个使用者重用
  • 基于契约[^3]: 功能和数据只能通过标准化服务契约[^3]公开
  • 一致性: 服务必须遵循一组通用的原则，交互方式，词汇和共享类型
  • 易于使用: 服务必须易于使用并且可有消费者组成
  • 可外部化: 服务的设计必须使它们提供的功能易于外部化。

我们将 REST/json 作为主要接口标准，并开发了全面的风格指南，
以帮助确保数百个可能在组织中构建服务端团队的一致性。其中包括 URL 结构、标头用法、查询参数、版本控制、资源命名、安全性、日志记录、错误处理、超媒体等内容。

我们还必须解决的是 API 契约[^3]档使用哪些格式。我们希望所有服务开发人员都使用相同得格式来记录其 API ，以便我们可以利用通用的工具和基础架构。

当我们开始时， API 市场还不成熟，实际上并没有事实上的 API 文档标准。最后我们采用了 Google 发现文档
（GDD），因此看起来还不错，也比大多数更好。从社区支持和采用的角度看，这很快就无济于事。我们最终为 GDD 开发了相当多得工具和支持，直到 2015 年中期
左右我们大多数开发人员都希望使用 OpenAPI（也叫 Swagger）。大约在那时，我们决定将所有 API 迁移到 OpenAPI 规范，并加入了
OpenAPI Initiative （OAI）。它的使用，使我们减少在基础设施的投资，获得了更大的收益。总体而言，它更强大，并且我们
的开发商更愿意使用。

参与过程

当你说 “管理” 一词是，大多数人会反感。感觉就像是 “大公司” 一词，是 “官僚主义” 和 “傲慢” 的同义词。人们想逃避。实际情况是，如果你要在大型，高度分散
的大型组织中强制执行标准和一致性，则不可避免地需要执行某种过程。重要得是要意识到这不仅仅是技术问题。与改变人类行为的真正难题相比，这相对容易。
良好的意图很好，但是需要某种形式的非可选过程来增强您想要的结果。就是说，是过程尽可能简单，轻巧和快速以最小化摩擦最大程度地提高满意度才是非常重要的。

我们开发的基本参与流程如下：

https://res.infoq.com/articles/paypal-api-first-part1/en/resources/1Picture1.jpg

当构建 API 的团队提交概述其计划，包括用例以及通常提议的设计的提议时，该过程开始。

  • 标准(Alignment)：一支中心团队于领域架构师和产品负责人协作，确定名称，命名空间，资源等。目标是是 API 适应更大得产品组合的范围，
    并确保从外而内的角度“有道理”（稍后会有更多介绍）。
  • 审核(Review)：团队使用标准格式记录API，并且跨领域的API设计专家团队提供有关如何提高可用性，一致性以及如何满足预期标准的反馈和建议。
    通常，这需要经过数次完善。
  • 评分(Score)：指定的API设计提交者根据一组反映设计标准的规范标准对API设计进行评分。
  • 验证(Verify)：API所有者验证其已审阅且由源代码控制的 API 契约[^3]是否与其基础服务实现相匹配。他们使用 API 一致性工具将CI作业中的请求/响应
    样本与版本化的API合同进行比较，并生成分数。

验证后，将部署基础API服务实现，并适当更新 API 的生命周期状态。客户现在知道该文档的哪个版本与他们的集成有关。

值得暂停一下以重申在此过程中客户满意度的重要性。这是我们在一开始就不足的领域。我们发现，尽管我们在设计流程方面做得很好，但我们还没有做好大规模操作
的准备。我们从根本上低估了所需的基础架构，而我们的手工步骤太多了。花费了太长时间，没有设定客户期望，并且每个问题和每个延迟都成为该过程的错误。
有很多投诉，我们需要迅速解决，否则可能会破坏整个工作。

该解决方案是多方面的，包括以下内容：

  • 加强自动化 许多步骤需要手动将事物从一种状态转移到另一种状态，更新数据并发出通知。通过自动化和自助服务，我们大大减少了盲目的工作，
    提高了响应速度，并使客户满意。您无法在电子表格中进行管理。
  • 设定现实的期望 按照定义，对开发人员施加新流程是一项新工作。开发人员需要了解 API 审查是他们需要纳入计划和说明的内容。他们还需要了解在软件
    开发生命周期中何时进行操作（提示：尽可能早地进行）。广泛的宣传和培训有助于设定切合实际的期望并提高满意度。
  • 倾听并迅速做出反应 您无法在第一时间得到正确的解决方案，因此请与客户交谈，并通过快速进行更改来向他们表明您的关心。这可以建立信任，
    并增强他们在下次参与时对流程的奉献精神。如果大多数开发人员了解更广阔的视野，他们希望您成功。他们会支持您并保持耐心，
    但您应归功于他们来倾听并偿还这种信任。

我们设法在大约四分之一的时间内大幅度减少了客户的投诉，直到今天，我们仍在不断重复这些方面的工作。如果能必须重来一次的话，
我们会启动时首先做更好的基础架构支持，其次是在营销和拓展方面花费更多时间来教育团队，设定期望并倾听反馈。与任何产品发布一样，如果要给您的客户一个
良好得体验并建立一个积极的反馈循环，最好延迟一点启动时间。

指标

大公司往往是非常受指标驱动的。每个产品和程序都可以归结为一个或两个指标以及仪表板上的状态。为了获得成功，您需要仔细考虑所衡量的内容，
与业务价值的关系以及如何为您的旅程设定正确的里程碑。

在 API 驱动的转换中，两个高级业务收益是降低集成成本和提高业务敏捷性。将您的业务功能重构为精心设计和记录良好的 API ，可以更轻松地在内部和外部与
合作伙伴和客户进行集成，并且可以使您以不同得创新方式快速重新组合功能。通过最大限度地减少多余得投资并扩展可寻址的市场，
这可以缩短产品上市时间并提高效率。不幸的是，很难直接归因和衡量这两个好处。您可能要做的最好得事情就是找到一个间接的指标，
该指标通过共识可以与这些更广泛得好处相关联。

我们解决这个问题的方法是开发一个成熟度模型，该模型表示 API 接近理想程度的一种质量得分。在这种情况下，“理想”是完全封装的服务，
该服务遵循所有API设计标准并且运行良好。这个想法是，当大多数业务功能通过高成熟度 API 服务公开时，业务利益将得到最佳实现。

以我们的标准为起点，我们创建了标准，并将其放置在1到5的范围内。我们还添加了一些标准，这些标准用于衡量 API 是否适合更广泛的业务能力组合，
并通过纳入SLA 标准来鼓励某些运营属性通过对成熟度模型进行版本控制
并控制每个标准在规模上的位置，我们已经能够逐步将API产品组合推向更理想的状态。我们根据失败的最低评分标准衡量每个API的成熟度得分。
这使我们能够使用简单的成熟度指标（对所有服务进行标准化）来汇总API产品组合的整体质量。

https://res.infoq.com/articles/paypal-api-first-part1/en/resources/1Picture2.jpg

上图是我们的一次记分记录，其中显示了 API 的成熟度评估。每个图像代表一个标准，这些标准源自我们要强制执行的标准。开发人员使用它可以快速了解通过了
哪些条件以及失败了的条件。他们单击每个按钮，深入研究细节，进行更正，并更新分数，直到达到成熟目标。在过去的几年中，我们同时改进了模型和基础架构。
现在，我们支持成熟度模型的多个同步版本，这使我们能够随着时间的推移不断发展和完善我们的标准，而不会破坏现有API的成熟度级别。
API可以在迭代和发布新得接口版本时升级到新的模型版本。

开发者网站

这部分基础架构可能是最重要的。鉴于大型组织的规模，您确实需要一个中心位置来整合所有 API ，所有文档，参与过程以及总体计划状态和进度。
这最终成为内部开发人员门户，与组织的行为进行沟通和协调至关重要。

刚开始，PayPal发生了一件非常有趣的事情。在启动我们的网站之前，我们已经在内部 Wiki 上开发了大部分标准和文档。没有人注意。
它丢失在混乱得文档和更新的文档中，而这些文档往往出现在任何长期的公司 Wiki 中。

作为实验，我们决定创建一个简单的网站，该网站的大部分静态内容与 Wiki上 已有的内容相同，为 95％ 。我们在 Intranet 上为其提供了不错的视觉设计和
一流的URL。我们花了一个星期来建造它。几乎一夜之间，情况发生了变化。高管们开始把这个网站称为“PayPal的未来”。它出现在演示文稿中，我们开始产生流量，
人们开始认真对待它。我们真正要做的只是改变包装，但观念却发生了根本变化。我们以为这会有所作为，但幅度真得让我们感到惊讶。突然，我们有了信誉，
并有了一定的发展动力。

这是一个转折点。那一刻也强化了从产品而不是从技术角度考虑程序的重要性。最后，我们要做的就是改变人们的行为。技术改造实际上只是副产品。为此，
您需要专注于客户并从他们的角度进行思考。这是我们的一课，我们已经将网站和程序发展为更加以客户为中心和更强大的功能。现在，
它是 PayPal 中访问量最大得内部应用程序之一。除了其他东西，这个网站提供：

  • 所有 API 的清单，包括接口，文档，样本，指标，所有权，反馈机制和成熟度评估详细信息。
  • 所有标准文档，版本信息和指南。
  • 版本化 API 合同的生命周期状态管理。
  • 在整个开发生命周期中提出和跟踪新API状态的参与过程。
  • 计划级别的报告和成熟度级别的仪表板，以及达到里程碑的进度。

这项投资并非微不足道，但实现该计划的目标绝对至关重要。

在下一篇文章中，我们将探讨如何使用此基础结构来帮助塑造API产品组合本身。其主要目标是在API之间建立清晰的边界，以鼓励以可预测的有用方式分解整体。

关于作者

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

[^1]: 被舍弃的选项中可能获得的最高价值；还指厂商把相同得生产要素投入到其他行业当中去可以获得的最高收益。 沉没成本（Sunk Cost，也叫沉淀成本）
是指由于过去的决策已经发生了的，而不能由现在或将来的任何决策改变的成本。
[^2]: 打开和服指的是向未来的新合伙人披露某一项目或本公司的内部运作情况。
[^3]: 契约，原文直译为 合同 ，表达的意思是 API（服务） 接口的全部信息，包括接口名称，参数，返回值，消息头等内容。