长期以来，API 一直是现代软件系统、架构和业务的支柱。他们现在主导着 Web，占所有 Internet 流量的 71%。生成式 AI 正在加速这一趋势，尤其是当我们将交互与常见的基于 Web 的功能（如“搜索”）转向 AI 丰富的变体时。更多的 AI 会带来更多的 API，因此，API 充当将数据移入和移出 AI 应用程序、AI 代理和大型语言模型 （LLM） 的重要机制。
也许最有趣的是，AI 本身将成为最大的 API 使用者，因为代理工作流代表我们执行自动化的 API 繁重的交互。我们是否能够迎合自助服务的机器消费者？随着我们奔向 AI 增强解决方案的新曙光，在过去十年中，庞大的 API 支持数字解决方案所面临的挑战（有些仍有待解决）是否会变得难以承受，从而对质量产生不利影响，并最终影响我们的成功？
在过去十年左右的时间里，用于改进 API 交付整体方法的一种方法是 API-First，这是一种简单的方法，首先侧重于查看和处理作为 API（或 API 集）提供的功能。然后，这些 API 构成了价值生成的构建块。
该方法鼓励将 API 视为以数字形式交付的基本元素，并最终将该接口与要解决的问题空间一起考虑。考虑接口契约旨在促进更好的互作性、一致性和重用性，而不受当前技术环境状态的束缚。
API-First 的原则
要更深入地了解，考虑 API-First 的一些原则可能会很有用。
- API 是突出的可交付成果： 在 UI 或通道之前，先关注 API 接口。虽然它们可能相关，但请将 API 视为第一个 UI，并从一开始就假设互作性，而不是处理集成后的后果。就好像我们构建的每个软件在其生命周期的某个时间点都需要连接一样进行规划。
- 预先设计：预先讨论、调整和定位 API 需求，以便在匆忙实施之前进行深思熟虑的 API 设计。
- 优先考虑消费者需求：关注消费者的观点，让内部领域知识或当前状态系统欺骗我们生成易于交付而不是易于使用的 API，从而避免成为提供商综合症的受害者。生产易于理解和使用的 API 的重要性被低估了。同样，内部系统的质量、数据结构、文档、暴露机制以及它们以消费者为中心的方式解决问题的能力也被高估了。在初始交付中跳过这一原则所感知到的短期收益将在不可避免的较长生产生命周期阶段对团队产生令人窒息的影响。
- 满足开发人员体验 （DX）： 了解好 DX 与坏 DX 的重要性以及它可能对平均集成时间产生的影响。如果可能，请构建特定于用例的数据结构，以便完成使用者作业。
API-First 的驱动程序或指示器
随着公司迈向数字化转型，已经有公认的业务、组织和技术驱动因素表明，采用 API 优先方法有可能获得真正的投资回报。随着公司努力取得进展并参与 AI 驱动的市场，其中许多相同的驱动因素正在重新出现。
组织驱动因素
- 接触新客户/市场（例如，嵌入式金融或新的 AI 市场）
- 提高客户满意度（或净推荐值）
- 希望成为全渠道（跨 Web、移动甚至 B2B 生态系统的可重用功能）
- 适应不断变化的市场条件（例如，我们准备好 AI 了吗？
- 确定直接收入机会
- 提高产品粘性（我们能否将我们的产品嵌入到多个客户工作流程中？
- 满足强制性法规要求（例如，开放银行法规）
- 提高内部效率（更清晰的业务领域、易于理解的能力以及跨业务线或地域的交互流程）
组织和技术驱动因素
- 架构向可组合性转变和/或组织向价值导向的团队转变
- 从整体式系统转向微服务
- 消除使用者的域复杂性
- 通过加强治理或标准化来提高 API 质量和非功能性需求 （NFR）
- 提高集成项目的成功率（许多企业最常见的薄弱环节）
- 改善团队沟通、协作和团队依赖关系洞察
- 减少孤立的不一致和开发人员的入职时间
- 意识到 API 使用者经常跨越组织或域边界
- 希望有一个受控的机制来解决技术债务
当然，并非所有驱动因素都适用于每个组织，但在战略实施时，通常了解要注意的事项可以作为有用的参考点。
建立指标和衡量预期结果同样重要，因为人们正在投资采用 API 优先方法。
业务和技术成果
有一些触觉区域能够衡量之前和之后的图片，作为对 API 优先实践的尝试。
商业优势
- 改进的 API 可发现性，从而实现更好的跨团队协作并提高功能重用率
- 提高了功能可见性和可观测性跨域价值交换
- 提高 API 的一致性和描述性，从而减少支持开销，并最终加快新创新和/或功能的上市时间
- 改善客户体验
组织和技术优势
- 为 API 使用者和提供商团队改善开发人员体验
- 透明的治理和标准管理充当团队推动者
- 提高 API 质量
- 改进的传统最薄弱环节 – 系统集成交接
- API 合约与实现分开，允许更积极的技术债务补救
- 更灵活（或可塑性更强）的团队结构
API 优先的替代视图或阻力
大规模实施 API 优先方法是一项非同小的练习。其根本原因是 API-First 涉及“人”。API 被视为社会技术资产是该方法的核心，因此它需要改变“人员”（包括技术和非技术）的工作和协作方式。
在组织内部，人们普遍反对采用 API-First，鉴于许多人渴望参与 AI 炒作的领域，也有一些新的框架。这是一个非详尽的列表：
API-First 不就是 Big Design Up Front （BDUF） 吗？
简单的答案是，不是的！就像任何形式的敏捷软件交付一样，我们应该努力了解我们可以交付的最小可行产品是什么对消费者有价值。对于 API，也不例外。不要试图为所有可能性进行设计。相反，请遵循良好的扩展性模式，以支持未来的发展，并根据当前需求设计“恰到好处”的 API。当您将此策略与 API 规范（如 OpenAPI、AsyncAPI 或 Arazzo）结合使用时，还会有额外的好处，因为您可以在对编写代码或创建测试套件进行任何投资之前获得该设计的快速反馈循环。
我们的团队配备了编写代码和发布代码的人员和设备——现在我们强迫他们处理其他格式，如 YAML、JSON、OpenAPI 等。这不就是让我们放慢脚步吗？
API-First 倡导我们真正考虑 API 的形状，并从消费者的角度来思考。快速处理像 OpenAPI 描述这样的工件，使您能够从使用者的角度预先验证许多问题。
有一个完整的工具生态系统，它们与各种样式的 API 中的许多规范兼容。互作性意味着团队无需过分担心处理其他格式的额外认知负担。如果您喜欢使用 YAML，那么总有一款工具适合您，同样，如果您更喜欢使用低代码可视化编辑器，甚至是更自然的面向语言的方法，也有适合您的工具。
围绕 API 规范的生态系统的这种丰富性在多个层面上都很重要。首先，它确保了架构弹性，因为组织不会被锁定在单个工具或供应商中。其次，各种经验大大降低了不同利益相关者群体参与的门槛，这进一步加强了这些 API 是社会技术资产的论点。第三，（可以说是最重要的）这些格式是我们向消费者（人类和机器）展示 API 的方式。因此，应该更多地关注它们的定性特性！
我们的 UI 就是我们的产品，现在某些 AI 模型可以直接使用 UI，那么我们为什么要转移重点呢？
当然，用户界面很重要，甚至是许多公司实现价值的差异化切入点。想想全球所有 UI 发挥重要作用的 SaaS 公司。然而，UI 本质上是瞬态的。它们随着趋势和人类体验期望而发展。UI 是否仅意味着面向 Web 或浏览器的界面？或者它还包括本机移动应用程序用户界面？即使在 SaaS 领域，消费者也可以通过许多其他渠道直接与产品进行交互，例如命令行界面 （CLI）、持续集成管道或直接通过 API 进行系统集成，这意味着 UI 只是任何消费者可能与 SaaS 提供商拥有的多个接触点之一。我们是否全面考虑了总体客户体验 （CX）？
在许多其他行业中，专有用户界面的使用正在下降。相反，公司希望通过直接集成到更大的 B2B 或 B2C 生态系统中来参与这些生态系统。嵌入式金融就是一个例子，预计到 2030 年，该市场将增长到 7.2 万亿美元以上。
Claude 的 AI 计算机使用是一个很好的创新示例，说明我们如何利用对用户界面的投资，让 AI 增强我们的人类工作流程，让人类将更多的灰质消耗在更高价值的活动上。这里有一个案例，尤其是在遗留接口领域，它可以发现短期价值，而不是花费精力创建漂亮的新 API。
好的 API 构建成本更低，并且比好的 UI 有更多的消费者选择，因此在这方面，API-First 可以帮助公司为未来做好准备，因为与 UI 相比，API 对 AI 代理的不可避免的转变要有用得多。
便利技术有反击的习惯，虽然可能会有短期收益，但也存在这些收益被高管误解为更便宜、更快、更一致的实现 AI 目标的方法。就像机器人流程自动化 （RPA） 一样，如果不与向 API 成熟度的并行架构转变相结合，它最终可能会成为一个昂贵且脆弱的热修复。
有价值的是数据，而不是传输管道;我们在捕获和管理数据方面投入了大量资金。API-First 对我们来说并不重要，因为我们可以提供对数据的访问。
确实，许多公司都在数据仓库、数据湖和数据工厂方面投入了大量资金。事实上，许多应用程序都拥有数 TB 甚至 PB 的数据。但是，如果没有上下文的关键要素，原始形式的数据，甚至在数据工厂中进行轻微转换的数据，几乎都毫无用处。提供对数据存储库的直接访问似乎很有效，但它通常会将解释和整合的负担减轻到消费者身上，从而导致混淆、误解，并最终导致容易出错的结果。在这方面要提防沉没成本谬误。
API 优先方法之所以强大，正是因为它从面向用例的思维方式开始，思考正在解决的问题以及如何以与该解决方案一致的方式最好地呈现数据。通过 API 深思熟虑地公开数据，公司可以封装特定于领域的知识，应用业务逻辑，并确保以安全、自助的方式提供数据，并根据实际业务需求量身定制。这种方法将数据情境化的责任从使用者转移回领域专家，从而减少了认知负担，并确保以更易用、更可靠的格式交付数据。
除了使数据更易于访问和有意义之外，API 还强制实施边界、保护敏感信息并防止意外暴露内部分类法或混乱的数据结构。数据成为域边界内的精选产品，支持受监管、一致且可扩展的集成方法。在将数据提供给 LLM 时，这一点变得更加重要。在 AI 驱动的世界中，API-First 不仅仅是连接到数据;它是关于提供安全、与域一致且为服务于特定目的而构建的价值和见解，从而提高流程中的生产力和准确性。
AI 世界中 API 优先的秘诀
虽然 AI 炒作周期可能会波动，但高质量 API 的基本原理保持不变，人类消费者受益的东西也将使新一波机器消费者受益。随着 AI 代理和自动化工作流程越来越依赖 API，我们需要确保我们的界面针对人类开发人员和 AI 模型进行优化。
来自 OpenAPI Initiative 等组织的新兴标准（包括 Arazzo 规范和覆盖规范）可在 API 交互中实现更丰富的语义和确定性，从而为 API 驱动的工作流带来上下文深度和适应性。
这些 API 驱动的工作流越来越多地与 AI 标准配合使用，例如 Anthropic 的模型上下文协议 （MCP），它为 AI 模型提供了一种标准化的方式来访问外部工具和数据源并与之交互。此类集成的有效性在很大程度上取决于 API 本身的设计。通过关注消费者（代理）体验和要完成的特定工作，团队可以创建 API，这些 API 不仅与 AI 代理的功能保持一致，还可以提高其效率和上下文理解（尤其是与 Arazzo 等工作流标准配对时）。这种方法确保我们不仅将精细的端点包装为 MCP 工具，而是提供有意义的高级功能，以推动智能和上下文感知的 AI 交互。
为了应对这种转变，以下是一些策略，可确保您的 API 足够强大，以支持 AI 驱动的应用程序：
- 强化 API 优先原则：从上面详述的 API 优先思维方式开始。当消费者是 AI 时，专注于前期设计、消费者需求和互作性将同样有价值，甚至更有价值。
- 利用 API 规范实现语义丰富性：OpenAPI 和 AsyncAPI 等 API 规范提供了 AI 模型进行可靠交互所需的架构驱动结构。规范允许您实施一致性、定义数据结构并提供明确的约束，所有这些都有助于机器使用者自信地与您的 API 交互。
- 超越参考文档：确保您的 API 文档不仅仅是技术参考。包括全面的示例、代码示例和面向用例的工作流程，以指导 AI 模型进行预期的交互。像 Arazzo 这样的规范将在使工作流程更易于访问、直观和可执行方面发挥关键作用，尤其是在我们迎合自主消费者的需求时。
- 优化 AI 代理和市场的可发现性：AI 模型和代理需要确定性、语义丰富的途径来发现和调用 API。像 Arazzo 这样的标准有助于以结构化、可解释的格式显示可用的作，从而推动以任务为中心的市场并实现自主工具编排。除了 MCP 之外，其他新兴协议也很重要。代理到代理 （A2A） 现在是 Linux Foundation 的一个项目，专注于通过共享工具使用和意图传播来协调代理，而代理通信协议 （ACP） 则为多代理系统正式化了结构化消息传递模式。除此之外，统一意图调解器 （UIM） 旨在通过丰富的元数据来提高可发现性，AI 驱动的代理可以解释和作这些元数据，确保 API 不仅可以访问，而且可以在自治系统中智能作。
- 提供可预测的服务等级协议 （SLA）：围绕速率限制、配额和可用性的可预测 SLA 使 AI 驱动型应用程序能够有效扩展，而不会遇到不可预见的障碍。由塞维利亚大学的研究人员开创的 SLA 项目（可能属于 OpenAPI 计划的保护伞）在这方面提供了潜力，有助于创建机器消费者可以依赖的定义、可靠的服务级别。
这些策略共同创建了一个有弹性的 AI 就绪型 API 基础设施。通过牢记这些原则来准备 API，您可以为当今的人类和机器消费者做好准备，同时也可以很好地适应 AI 增强环境中的未来变化。