中文
API 是云原生应用的“结缔组织”，应用的组件微服务通过 API 进行通信。随着应用的增长和扩展，微服务和 API 的数量不断增加。虽然在大多数情况下，这是无法避免的结果，但确实也给负责确保现代应用可靠性、可扩展性和安全性的平台运维团队带来了重大挑战。我们把这个问题称为 API 泛滥，并在之前的一篇博文中谈论过该问题。
为了解决 API 泛滥，企业首先可能会尝试使用自上而下的方法，即实施 API 自动发现和修复工具。虽然这在短期内行之有效，但通常会给负责构建和运维 API 与微服务的团队带来不必要的负担。他们要么必须改造现有微服务和 API 以解决安全和合规问题，要么必须经历繁杂的审查流程以获得所需的审批。因此，许多大型软件企业都采用去中心化的方法，即通过自适应治理赋予开发人员所需的自主权。
从长远来看，自下而上的问题处理方法比在最后时刻采取保障措施更为有效。具体来说，企业中负责为不同的微服务与应用构建和运维 API 的团队最先参与进来，而且通常从采用 API 优先的软件开发方法开始。
什么是 API 优先？
API 已问世数十年。但如今它们不再只是简单的“应用程序编程接口”。从本质上说，API 就是开发人员接口。与任何用户界面一样，API 需要规划、设计和测试。API 优先是指所有运维和使用 API 的团队都承认并优先考虑连通性和简易性的重要性。它强调面向 API 消费者的通信、可复用性和功能性，这些 API 消费者几乎都是开发人员。
实现 API 优先有很多途径，但设计主导式的软件开发方法是大多数公司开启 API 优先之旅的最终目标。在实践中，该方法意味着 API 在实施之前就已定义完毕。一切从设计和记录 API 如何运行开始。团队依靠由此产生的交付物——通常被称为 API 契约——来获知如何实施应用程序的功能。
请参阅由 NGINX 提供的 O’Reilly 电子书《掌握 API 架构》的第 1 章，了解设计技术如何为可靠且灵活的 API 优先软件开发方法提供支持。
API 优先给组织的价值
API 优先策略通常是微服务架构的理想选择，因为它可确保应用程序生态系统以模块化、可复用的系统形式出现。采用 API 优先的软件开发模式能够为开发人员和组织带来显著的优势，包括：
- 提高开发人员的生产力——开发团队能够并行工作，他们能够更新后端应用，而不影响开发其他依赖于应用 API 的微服务的团队。API 全生命周期协作通常会变得更轻松，因为每个团队都可以参考既定 API 契约 (contract)。
- 增强开发人员体验——API 优先设计可通过确保 API 合乎逻辑且有据可查来改善开发人员体验。这能够为与 API 交互的开发人员提供无缝体验。了解为何平台运维团队必须将 API 开发人员的体验考虑在内。
- 确保一致的治理和安全防护——云和平台架构师可通过在 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 定义的标准规范。它提供机器可读的契约描述给定 API 如何工作。OpenAPI 规范在各种 API 管理和 API 网关工具（包括 NGINX）中受到广泛支持。后文将重点介绍您如何使用 OpenAPI 规范来完成一些重要的用例。
OpenAPI 规范是一种开源格式，用于以 JSON 或 YAML 格式定义 API。您可以添加广泛的 API 特性，如下方简易 API 示例所示。下面简单的 HTTP GET 请求返回了一个虚拟购物清单的明细。
openapi: 3.0.0
info:
version: 1.0.0
title: Grocery List API
description: An example API to illustrate the OpenAPI Specification
servers:
url: https://api.example.io/v1
paths:
/list:
get:
description: Returns a list of stuff on your grocery list
responses:
'200':
description: Successfully returned a list
content:
schema:
type: array
items:
type: object
properties:
item_name:
type: string遵循 OpenAPI 规范的定义人机均可读。这意味着有一个单一的信息源记录着每个 API 的运行情况，这在有多个团队负责 API 构建和运维的企业中特别重要。当然，为了大规模地管理、治理和保护 API，您需要确保 API 平台中的其他工具——API 网关、开发者门户和高级安全防护——也支持 OpenAPI 规范。
请参阅《掌握 API 架构》的第 1 章，深入了解如何使用 OpenAPI 规范来设计 REST API。
采用通用 API 规范的好处
采用通用 API 规范，例如 OpenAPI 规范，有几个好处：
- 更高的互操作性——通用的机器可读的规范意味着不同的系统和客户端都可以消费和使用 API 契约。这支持平台运维团队更轻松地集成、管理和监控复杂的架构。
- 一致的文档——API 契约以标准格式编写，包括端点、请求和响应格式以及其他相关细节。许多系统都可以使用 API 契约来生成完备的文档，而且内容清晰明了，支持开发人员更轻松地理解如何使用 API。
- 更出色的测试——API 规范可用于自动生成和运行测试，这有助于确保 API 是符合契约并按预期运行的。可靠的测试可帮助在将 API 发布到生产环境之前发现问题。
- 更高的安全性——高级安全工具可以使用 OpenAPI 规范来分析 API 流量和用户行为。这些工具将使用主动安全防护的方法，来验证 API 请求是否符合 API 端点所支持的方法、端点和参数。在默认情况下，违规流量会被拦截，从而减少您的微服务需要处理的调用数量。
- 更轻松的演进——API 规范可以提供一种清晰标准的方式来记录和传达人机均可读的格式的变化，从而促进 API 契约和应用本身的演进。结合适当的版本控制实践，这有助于最大限度地降低 API 变更对 API 消费者的影响，并确保 API 保持向后兼容。
总的来说，使用通用的 API 规范可帮助改进 API 的互操作性、文档、测试、安全性和逐步演进。
NGINX 如何支持 API 优先的软件开发
NGINX 提供了一套轻量级云原生工具，支持大规模运维、监控、治理和保护 API 更加容易。举例来说，API Connectivity Manager（F5 NGINX Management Suite 的一部分）为您的 API 运维提供了一个单一管理平面。它支持您配置并管理 API 网关和开发者门户。作为一套 API 优先的工具，其各项功能均可通过 REST API 进行访问，因此 DevOps 团队能够轻松实现 CI/CD 自动化和集成。
借助 OpenAPI 规范，您可以使用 NGINX 产品：
将 API 发布到 API 网关
API Connectivity Manager 使用 OpenAPI 规范来简化 API 发布和管理。API 开发人员可以使用 NGINX Management Suite 用户界面或完全申明式 的REST API 将 API 发布到 API 网关。API 被添加至网关，作为 API 代理，其中包括 API 网关将传入 API 请求引导至后端微服务所需的全部 Ingress、后端和路由配置。借助 REST API，您可通过使用 Ansible 等工具简单地创建 CI/CD 自动化脚本，将 API 作为代码进行部署和管理。
关于使用 OpenAPI 规范发布 API 的完整说明，请参阅 API Connectivity Manager 文档。
为开发者门户生成 API 文档
对 API 团队来说，维护文档往往是一个令人头痛的问题。开发者门户上的大量过时文档也是 API 泛滥的一大症状。API Connectivity Manager 使用 OpenAPI 规范自动生成文档并将其发布到开发者门户，这可帮助 API 开发人员节省时间，并确保 API 消费者总能找到需要的内容。您可以直接通过 API Connectivity Manager 用户界面或 REST API 上传 OpenAPI 规范文件。
关于发布 API 文档到开发者门户的完整说明，请参阅 API Connectivity Manager 文档。
使用主动安全策略来保护 API 端点
您也可以使用 OpenAPI 规范来验证对 NGINX Plus API 网关的 API 请求是否符合 API 支持的类型。通过使用主动安全策略（一种定义允许和拒绝列表的安全模型），可以防止恶意请求探测后端服务的潜在漏洞。
在撰写本文时，您尚不能使用 API Connectivity Manager 来配置 NGINX App Protect WAF；这一功能将在 2023 年晚些时候发布。但是，您可以使用 Instance Manager（另一个 NGINX Management Suite 模块）和 OpenAPI 规范为 WAF 编写自定义策略。更多信息，请参阅 NGINX App Protect WAF 和 Instance Manager 文档。
请参阅《掌握 API 架构》的第 7 章，进一步了解 API 安全和威胁建模以及如何在 API 网关上应用身份验证和授权。
总结
采用 API 优先的方法来构建微服务和应用能够为企业带来诸多优势。根据 OpenAPI 规范（或者其他的人机均可读的通用 API 规范）来协调团队有助于实现跨团队协作、沟通和运维。
现代应用在复杂的云原生环境中运行。采用支持 API 优先方法的工具来运维 API 是实现 API 优先策略的关键一步。借助 NGINX 解决方案，您可以使用 OpenAPI 规范在分布式团队和环境中大规模地管理 API。
立即开启 NGINX Management Suite 30 天免费试用，包括 API Connectivity Manager、NGINX Plus（作为 API 网关）及 NGINX App Protect（可保护 API）。
