采用 API 优先方法构建微服务的好处

API 是云原生应用的连接组织，是应用程序组件微服务进行通信的手段。 随着应用的增长和扩展，微服务和 API 的数量也在增加。 虽然在大多数情况下这是不可避免的结果，但它给负责确保现代应用的可靠性、可扩展性和安全性的平台运营团队带来了重大挑战。 我们将这个问题称为API 蔓延，并在之前的博客文章中对其进行了详细描述。

作为解决 API 蔓延的首次尝试，组织可能会尝试采用自上而下的方法，实施自动 API 发现和修复工具。 虽然这在短期内是有效的，但它往往会给负责构建和运营 API 和微服务的团队带来过度的负担。 他们要么必须重新设计现有的微服务和 API 来解决安全性和合规性问题，要么经过艰苦的审查过程才能获得所需的批准。 这就是为什么许多大型软件组织采用分散式方法，使用自适应治理来赋予开发人员所需的自主权。

与最后一刻采取保障措施相比，自下而上地解决问题从长远来看更为有效。 为不同的微服务和应用构建和操作 API 的团队是第一批参与的团队，并且通常首先在组织中采用API 优先的方法进行软件开发。

什么是 API-First？

API 已经存在几十年了。 但它们不再仅仅是“应用程序编程接口”。 从本质上讲，API 是开发人员界面。 与任何用户界面一样，API 需要规划、设计和测试。 API‑first 是指在所有操作和使用 API 的团队中承认并优先考虑连接性和简单性的重要性。 它优先考虑 API 消费者（几乎总是开发人员）的通信、可重用性和功能。

实现 API 优先的途径有很多，但对于大多数踏上 API 优先之旅的公司来说，以设计为主导的软件开发方法是最终目标。 实际上，这种方法意味着 API 在实现之前就已经完全定义好了。 工作从设计和记录 API 如何运行开始。 团队依靠最终的工件（通常称为API 合同）来告知他们如何实现应用程序的功能。

在电子书《掌握 API 架构》第 1 章（由 O'Reilly 出版）中探索支持 API 优先软件开发方法的设计技术，这种方法既耐用又灵活，并附有 NGINX 的说明。

API-First 对组织的价值

API 优先策略通常是微服务架构的理想选择，因为它可以确保应用生态系统以模块化和可重用系统的形式开始。 采用 API 优先的软件开发模型可以为开发人员和组织带来显著的好处，包括：

• 提高开发人员的工作效率——开发团队可以并行工作，能够更新后端应用，而不会影响依赖于应用API 的其他微服务的团队。 由于每个团队都可以参考已建立的 API 契约，因此整个 API 生命周期内的协作通常更容易。
• 增强开发人员体验——API 优先设计通过确保 API 的逻辑性和完善的文档性来优先考虑开发人员体验。 这为开发人员在与 API 交互时创造了无缝体验。了解平台运营团队为何如此重视 API 开发人员体验<.htmla>。
• 一致的治理和安全——云和平台架构师可以在 API 设计阶段纳入安全和治理规则，以一致的方式组织 API 生态系统。 这避免了在软件流程后期发现问题时所需的昂贵审查。
• 提高软件质量——首先设计 API 可确保在开发过程的早期（即 API 准备好部署到生产之前）满足安全性和合规性要求。 由于不需要修复生产中的安全漏洞，您的运营、质量和安全工程团队有更多时间直接与开发团队合作，以确保在设计阶段满足质量和安全标准。
• 更快的上市时间——通过更少的依赖性和一致的服务间通信框架，不同的团队可以更有效地构建和改进他们的服务。 一致的、机器可读的 API 规范是一种可以帮助开发人员和平台运营团队更好地协同工作的工具。

总体而言，采用 API 优先方法可以帮助公司构建更灵活、可扩展且安全的微服务架构。

采用通用 API 规范有何帮助

在典型的企业微服务和 API 环境中，发挥作用的组件数量比平台运营团队日常可以跟踪的数量还要多。 采用标准的、机器可读的 API 规范有助于团队了解、监控和决策当前在其环境中运行的 API。

采用通用 API 规范也有助于在 API 设计阶段改善与利益相关者的协作。 通过制定 API 合同并将其正式化为标准规范，您可以确保所有利益相关者对 API 的工作方式达成共识。 它还使得跨团队共享可重复使用的定义和功能变得更加容易。

目前有三种常见的 API 规范，每种规范都支持大多数类型的 API：

• OpenAPI – 所有 Web API 和 Webhook 的 JSON 或 YAML 描述
• AsyncAPI – 事件驱动 API 的 JSON 或 YAML 描述
• JSON Schema – 用于 API 的模式对象的 JSON 描述

REST API 构成了当今生产中的大多数 API，而 OpenAPI 规范是编写 REST API 定义的标准方式。它提供了机器可读的契约，描述了给定 API 的功能。 OpenAPI 规范得到了各种 API 管理和 API 网关工具（包括 NGINX）的广泛支持。本博客的其余部分将重点介绍如何使用 OpenAPI 规范来实现一些重要的用例。

OpenAPI 规范是一种以 JSON 或 YAML 定义 API 的开源格式。 您可以包含各种 API 特性，如下面的简单 API 示例所示。 这里，一个简单的 HTTP GET请求返回一个假想购物清单上的物品列表。

打开API： 3.0.0信息：
版本： 1.0.0
标题： 购物清单 API
描述： 用于说明 OpenAPI 规范的示例 API

服务器：
url：https://api.example.io/v1

路径：
/list：
获取：
说明： 返回您的购物清单上的物品列表
响应：
        '200':
描述： 成功返回列表
内容：
架构：
类型：数组
项目：
类型：对象
属性：
项目名称：
类型：字符串

遵循 OpenAPI 规范的定义既可人读又可机器读。 这意味着有一个单一的真实来源来记录每个 API 的功能，这在拥有许多团队构建和操作 API 的组织中尤为重要。 当然，为了大规模管理、管理和保护 API，您需要确保 API 平台中的其他工具（API 网关、开发人员门户和高级安全）也支持 OpenAPI 规范。

在《掌握 API 架构》第 1 章中深入了解如何使用 OpenAPI 规范设计 REST API。

采用通用 API 规范的好处

使用通用 API 规范（例如 OpenAPI 规范）有几个好处：

• 提高互操作性——通用的、机器可读的规范意味着不同的系统和客户端可以使用 API 契约。 这使得平台运营团队更容易集成、管理和监控复杂的架构。
• 一致的文档——API 契约以标准格式记录，包括端点、请求和响应格式以及其他相关细节。 许多系统可以使用合同生成全面的文档，提供清晰度并使开发人员更容易理解如何使用 API。
• 更好的测试——API 规范可用于自动生成和运行测试，这有助于确保 API 实现遵守合同并按预期工作。 这有助于在 API 发布到生产环境之前识别其存在的问题。
• 提高安全性– 高级安全工具可以使用 OpenAPI 规范来分析 API 流量和用户行为。 他们可以通过验证 API 请求是否符合 API 端点支持的方法、端点和参数来应用积极的安全性<.htmla>。 默认情况下，不符合要求的流量会被阻止，从而减少微服务必须处理的调用次数。
• 更容易演进——API 规范可以提供一种清晰、标准的方式来记录和传达机器和人类可读格式的变化，从而促进 API 合同和应用本身随着时间的推移而演进。 与适当的版本控制实践相结合，这有助于最大限度地减少 API 更改对 API 消费者的影响，并确保 API 保持向后兼容。

总体而言，使用通用 API 规范有助于提高 API 的互操作性、文档、测试、安全性和逐步发展。

NGINX 如何支持 API 优先的软件开发

NGINX 提供了一组轻量级、云原生工具，可以轻松大规模操作、监控、管理和保护 API。 例如， F5 NGINX 管理套件的一部分API 连接管理器为您的 API 操作提供了单一管理平面。 有了它，您可以配置和管理 API 网关和开发人员门户。 作为 API 优先工具，每个功能都可以通过 REST API 访问，这使得DevOps团队可以轻松实现 CI/CD 自动化和集成。

使用 OpenAPI 规范，您可以使用 NGINX 产品来：

• 将 API 发布到 API 网关
• 为开发人员门户生成 API 文档
• 应用积极的安全措施来保护 API 端点

将 API 发布到 API 网关

API 连接管理器使用 OpenAPI 规范来简化 API 的发布和管理。 API 开发人员可以使用 NGINX Management Suite 用户界面或完全声明式 REST API 将 API 发布到 API 网关。API 以 API 代理的形式添加到网关，其中包含 API 网关将传入的 API 请求定向到后端微服务所需的所有入口、后端和路由配置。 您可以使用 REST API 通过使用 Ansible 等工具创建简单的 CI/CD 自动化脚本来部署和管理 API 作为代码。

有关使用 OpenAPI 规范发布 API 的完整说明，请参阅API 连接管理器文档。

为开发者门户生成 API 文档

维护文档通常是 API 团队的一件令人头疼的事。 但开发者门户上的过时文档也是 API 蔓延的一个主要症状。 API 连接管理器使用 OpenAPI 规范自动生成文档并将其发布到开发人员门户，从而节省 API 开发人员的时间并确保 API 消费者始终能够找到他们需要的内容。 您可以通过 API 连接管理器用户界面或 REST API 直接上传 OpenAPI 规范文件。

有关将 API 文档发布到开发者门户的完整说明，请参阅API 连接管理器文档。

应用积极的安全措施来保护 API 端点

您还可以使用 OpenAPI 规范来验证对 NGINX Plus API 网关的 API 请求是否符合 API 支持的内容。 通过应用积极的安全性（一种定义允许的内容并阻止其他所有内容的安全模型），您可以防止恶意请求探测后端服务中的潜在漏洞。

在撰写本文时，您无法使用 API Connectivity Manager 来配置NGINX App Protect WAF ；此功能将于 2023 年晚些时候推出。 但是，您可以使用实例管理器（另一个 NGINX 管理套件模块）和 OpenAPI 规范为您的 WAF 编写自定义策略。 有关更多信息，请参阅NGINX App Protect WAF和Instance Manager的文档。

在《掌握 API 架构》的第 7 章中了解有关 API 安全性和威胁建模的更多信息，以及如何在 API 网关处应用身份验证和授权。

概括

采用 API 优先方法构建微服务和应用可以在多方面使您的组织受益。 围绕 OpenAPI 规范（或其他人类和机器可读的通用 API 规范）协调团队有助于实现跨团队的协作、沟通和运营。

现代应用在复杂的云原生环境中运行。 采用支持以 API 优先方法操作 API 的工具是实现 API 优先策略的关键一步。 使用 NGINX，您可以使用 OpenAPI 规范来跨分布式团队和环境大规模管理 API。

开始30 天 NGINX 管理套件免费试用，其中包括访问API 连接管理器、作为 API 网关的NGINX Plus以及用于保护您的 API 的NGINX App Protect 。