API 是云原生应用的连接组织,是应用程序组件微服务进行通信的手段。 随着应用的增长和扩展,微服务和 API 的数量也在增加。 虽然在大多数情况下这是不可避免的结果,但它给负责确保现代应用的可靠性、可扩展性和安全性的平台运营团队带来了重大挑战。 我们将这个问题称为API 蔓延,并在之前的博客文章中对其进行了详细描述。
作为解决 API 蔓延的首次尝试,组织可能会尝试采用自上而下的方法,实施自动 API 发现和修复工具。 虽然这在短期内是有效的,但它往往会给负责构建和运营 API 和微服务的团队带来过度的负担。 他们要么必须重新设计现有的微服务和 API 来解决安全性和合规性问题,要么经过艰苦的审查过程才能获得所需的批准。 这就是为什么许多大型软件组织采用分散式方法,使用自适应治理来赋予开发人员所需的自主权。
与最后一刻采取保障措施相比,自下而上地解决问题从长远来看更为有效。 为不同的微服务和应用构建和操作 API 的团队是第一批参与的团队,并且通常首先在组织中采用API 优先的方法进行软件开发。
API 已经存在几十年了。 但它们不再仅仅是“应用程序编程接口”。 从本质上讲,API 是开发人员界面。 与任何用户界面一样,API 需要规划、设计和测试。 API‑first 是指在所有操作和使用 API 的团队中承认并优先考虑连接性和简单性的重要性。 它优先考虑 API 消费者(几乎总是开发人员)的通信、可重用性和功能。
实现 API 优先的途径有很多,但对于大多数踏上 API 优先之旅的公司来说,以设计为主导的软件开发方法是最终目标。 实际上,这种方法意味着 API 在实现之前就已经完全定义好了。 工作从设计和记录 API 如何运行开始。 团队依靠最终的工件(通常称为API 合同)来告知他们如何实现应用程序的功能。
在电子书《掌握 API 架构》第 1 章(由 O'Reilly 出版)中探索支持 API 优先软件开发方法的设计技术,这种方法既耐用又灵活,并附有 NGINX 的说明。
API 优先策略通常是微服务架构的理想选择,因为它可以确保应用生态系统以模块化和可重用系统的形式开始。 采用 API 优先的软件开发模型可以为开发人员和组织带来显著的好处,包括:
总体而言,采用 API 优先方法可以帮助公司构建更灵活、可扩展且安全的微服务架构。
在典型的企业微服务和 API 环境中,发挥作用的组件数量比平台运营团队日常可以跟踪的数量还要多。 采用标准的、机器可读的 API 规范有助于团队了解、监控和决策当前在其环境中运行的 API。
采用通用 API 规范也有助于在 API 设计阶段改善与利益相关者的协作。 通过制定 API 合同并将其正式化为标准规范,您可以确保所有利益相关者对 API 的工作方式达成共识。 它还使得跨团队共享可重复使用的定义和功能变得更加容易。
目前有三种常见的 API 规范,每种规范都支持大多数类型的 API:
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 规范(例如 OpenAPI 规范)有几个好处:
总体而言,使用通用 API 规范有助于提高 API 的互操作性、文档、测试、安全性和逐步发展。
NGINX 提供了一组轻量级、云原生工具,可以轻松大规模操作、监控、管理和保护 API。 例如, F5 NGINX 管理套件的一部分API 连接管理器为您的 API 操作提供了单一管理平面。 有了它,您可以配置和管理 API 网关和开发人员门户。 作为 API 优先工具,每个功能都可以通过 REST API 访问,这使得DevOps团队可以轻松实现 CI/CD 自动化和集成。
使用 OpenAPI 规范,您可以使用 NGINX 产品来:
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 连接管理器使用 OpenAPI 规范自动生成文档并将其发布到开发人员门户,从而节省 API 开发人员的时间并确保 API 消费者始终能够找到他们需要的内容。 您可以通过 API 连接管理器用户界面或 REST API 直接上传 OpenAPI 规范文件。
有关将 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 。
“这篇博文可能引用了不再可用和/或不再支持的产品。 有关 F5 NGINX 产品和解决方案的最新信息,请探索我们的NGINX 产品系列。 NGINX 现在是 F5 的一部分。 所有之前的 NGINX.com 链接都将重定向至 F5.com 上的类似 NGINX 内容。”