为什么您需要一个 API 开发者门户来进行 API 发现

企业越来越依赖 API 来连接跨业务线的应用和数据、与合作伙伴整合并提供客户体验。 据TechRadar统计，如今平均每个企业总共利用 15,564 个 API，同比增长 201%。

随着 API 数量的不断增长，管理 API 组合的复杂性也随之增加。 发现和追踪可用的 API 以及它们位于何处，以及查找有关如何使用它们的文档变得越来越困难。 如果没有整体的 API 策略，API 的增长速度将超过平台运营团队的管理速度。 我们将这个问题称为API 蔓延，并在之前的文章中解释了为什么它是一个如此严重的威胁。 在这篇文章中，我们将详细探讨如何在 NGINX 的帮助下建立 API 开发人员门户来对抗 API 蔓延。

建立 API 清单

归根结底，API 只有被使用才有用，这意味着 API 消费者需要一种方法来找到它们。 如果没有适当的系统，API 蔓延会让开发人员很难找到他们的应用所需的 API。 最好的情况是，API 列表由不同的业务线保存，知识通过非正式的工程师网络在团队之间共享。

对抗 API 蔓延的第一步是为您的 API 创建单一真实来源。 该过程从建立 API 清单开始。 然而，准确的清单是一项挑战——随着新 API 的引入和旧 API 的弃用，它是一个不断变化的目标。 您还需要在您的环境中找到任何“影子 API”——那些随着时间的推移而被遗忘的 API、被不适当地弃用的 API 或在标准流程之外构建的 API。

非托管 API 是 API 蔓延最隐蔽的症状之一，既有明显的安全隐患，又有隐性成本。 如果没有可用 API 的准确清单，您的 API 团队必须花时间寻找文档。 由于各个团队构建类似的功能，因此存在重复劳动浪费的巨大风险。 如果没有适当的版本控制，对给定 API 的更改可能会导致代价高昂的返工甚至停机。

自动 API 发现等技术可以帮助您识别和治疗非托管 API 的症状。 但要解决这个问题，你需要消除根本原因：流程中断和缺乏所有权。 实际上，将 API 库存和文档集成到您的 CI/CD 管道中是确保您的 API 产品组合长期可见的唯一方法。 您无需在每个 API 上线时手动跟踪它，而只需识别和补救异常。

使用 API 开发人员门户简化 API 发现

简化 API 发现是 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 团队增加更多工作。

使用 NGINX 为您的 API 创建单一事实来源

为了实现无缝 API 发现，您需要创建一个单一事实来源，让开发人员可以在其中找到您的 API、了解如何使用它们以及将它们纳入他们的项目中。 这意味着您需要一个开发人员门户和最新的文档。

API 连接管理器是 F5 NGINX 管理套件的一部分，可帮助您将 API 的发布、版本控制和文档直接集成到开发工作流程中，因此您的 API 开发人员门户永远不会过时。 除了可以轻松创建 API 开发人员门户来托管您的 API 和文档之外，API Connectivity Manager 还允许您添加自定义页面并完全自定义开发人员门户以匹配您的品牌。

让我们看看 API Connectivity Manager 如何帮助您解决一些特定的用例。 有关设置开发人员门户集群和发布开发人员门户的详细说明，请参阅 API Connectivity Manager 文档。

自动生成 API 文档

API 消费者对文档的质量和细节水平的期望与忙碌的 API 开发人员在有限的时间和资源下实际能够交付的内容之间往往存在很大差距。 许多自主开发的文档工具无法与开发生命周期或其他工程系统集成。 事实并不一定如此。

NGINX 如何提供帮助： API Connectivity Manager 使用OpenAPI 规范将 API 发布到 API 网关，并在开发者门户上自动生成随附文档，节省 API 开发人员的时间并确保 API 消费者始终能够找到他们需要的内容。 您可以直接通过 API 连接管理器用户界面上传 OpenAPI 规范文件，也可以通过 REST API 发送调用。这样就可以轻松地通过 CI/CD 管道自动执行文档流程。

要在 API Connectivity Manager 中发布文档，请单击左侧导航栏中的“服务”以打开“服务”选项卡。 单击您的工作区名称或创建一个新的工作区。

进入工作区后，单击包含工作区名称和描述的框下方的API 文档（屏幕截图中的example-api ）。 只需单击添加 API 文档按钮即可上传您的 OpenAPI 规范文件。 单击“保存”按钮将文档发布到开发者门户。

确保正确的版本

版本变更必须始终谨慎处理，在微服务环境中尤其如此，因为许多服务可能与单个 API 交互。如果不谨慎地引入新版本并淘汰旧版本，一个重大变更就可能导致数十个微服务发生连锁中断。

NGINX 如何提供帮助： 将 OpenAPI 规范文件与 API 连接管理器结合使用，可以轻松对您的 API 进行版本控制。 除了设置版本号之外，您还可以为每个版本提供文档并管理其状态（最新、活跃、已退役或已弃用）。

要发布 API 的新版本，请单击左侧导航栏中的“服务” 。 单击表中您的工作区的名称，然后在打开的页面上单击您的环境的名称。 接下来，单击+ 添加代理按钮。 从这里您可以上传 OpenAPI 规范，设置基本路径和版本以创建 URI（例如， /api/v2/ ），并输入其他重要元数据。 单击发布按钮保存并发布您的 API 代理。

API 的原始版本与新版本一起保持可用。 这使您的用户有时间逐步将其应用或服务迁移到最新版本。 准备就绪后，您可以完全弃用 API 的原始版本。图 2 显示了已发布和投入生产的两个版本的 Sentence Generator API。

生成 API 凭证

为了推动 API 的采用，您需要尽可能简化 API 使用者的上线流程。 一旦用户找到他们的 API，他们就需要一种方法来安全地登录开发者门户并生成凭证。 这些凭证授予他们访问 API 功能的权限。通常，您需要实施自我管理的工作流程，以便用户可以自行注册。

NGINX 如何提供帮助： API Connectivity Manager 支持开发人员门户上的自我管理 API 工作流，因此用户可以生成自己的资源凭证来访问 API。 可以使用API 密钥或HTTP 基本身份验证在门户上管理资源凭证。 您还可以在开发人员门户上启用单点登录 (SSO) 来安全访问并允许经过身份验证的 API 使用者管理资源凭证。

要在开发者门户上快速启用 SSO，请单击左侧导航栏中的“基础设施” 。 单击表中您的工作区的名称（在图 3 中，它是team-sentence ）。

在工作区页面的表格中，单击要配置的环境的名称（在图 4 中，它是prod ）。

在开发者门户集群部分，单击您正在处理的开发者门户的操作列中的...图标，然后从下拉菜单中选择编辑高级配置。 在图 5 中，单个开发者门户集群是devportal-cluster 。

接下来，单击左侧导航栏中的“全局策略” 。 通过单击其行的“操作”列中的...图标并从下拉菜单中选择“编辑策略”来配置OpenID Connect 依赖方策略。 有关更多信息，请参阅API 连接管理器文档。

在开发者门户上试用 API

衡量 API 策略成功与否的一种方法是跟踪“首次 API 调用时间”指标，该指标可揭示开发人员使用 API 发送基本请求所需的时间。

我们已经确定，清晰、简洁的文档是 API 的第一个切入点，用户可以通过它了解如何使用 API。通常，开发人员必须编写新代码将 API 集成到他们的应用中，然后才能测试 API 请求。 您可以通过提供一种使用真实数据直接与开发人员门户上的 API 交互的方法来帮助开发人员更快地开始使用 - 有效地进行他们的第一个 API 调用，而无需为他们的应用编写一行代码！

NGINX 如何提供帮助： 一旦您为 API Connectivity Manager 开发人员门户启用 SSO，API 使用者就可以使用 API Explorer 在您的文档页面上尝试 API 调用。 他们可以使用 API Explorer 探索 API 的端点、参数、响应和数据模型，并直接使用浏览器测试 API 调用。

图 7 显示了 API Explorer 的实际运行情况 - 在本例中，尝试使用 Sentence Generator API。用户选择适当的凭据，创建请求，并接收来自 API 的实际数据的响应。

概括

API 对于您的组织至关重要。 管理和保护 API 的第一步是从对每个 API 进行盘点开始，无论它位于何处。 但是 API 发现只是解决方案的一部分——您需要在开发和工程生命周期中构建 API 清单、文档和版本控制，以解决 API 蔓延的根本原因。

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