为何需要通过API开发者门户发现API

NGINX | 2022年12月06日

企业越来越依赖API来连接不同业务线的应用和数据、与合作伙伴集成，并提供客户体验。据TechRadar称，如今每家企业平均使用15,564个API，同比增长201%。

随着API数量持续增长，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清单和文档集成到CI/CD流水线，是长期确保整个API组合可见性的可行方法。这样无需在每个API上线时手动跟踪，只需识别并修复例外情况。

借助API开发者门户简化API发现

API开发者门户可以帮助简化API发现。它为API使用者提供一个集中位置，便于发现API、阅读文档，并在将API集成到应用程序之前进行试用。API开发者门户还可以作为中央API目录，提供所有权和联系信息，让所有人都能了解由谁负责维护不同服务的API。

作为我们的API参考架构<.htmla>的核心组件，高效的API开发者门户可支持以下几个关键用例：

API策略需要涵盖API开发者门户的维护方式。您需要一种自动化、低干预的方法，无缝整合API发布、版本管理和文档编制，同时不给API团队增加额外工作。

使用NGINX为API创建单一可信来源

要实现顺畅的API发现，需要建立统一可信的信息源，让开发人员能够查找API、了解其使用方法，并将其接入项目。这意味着需要一个开发者门户和保持最新的文档。

API Connectivity Manager是F5 NGINX Management Suite的一部分，可帮助您将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 Connectivity Manager 用户界面上传 OpenAPI 规范文件，也可以通过 REST API 发送调用。这样便可通过 CI/CD 流水线轻松实现文档流程自动化。

要在API Connectivity Manager中发布文档，请单击左侧导航栏中的“Services”，打开“Services”选项卡。单击Workspace名称，或“新建Workspace”。

进入Workspace后，点击显示Workspace名称和说明的框下方的API Docs（截图中为example-api）。点击Add API Doc按钮，上传OpenAPI Specification文件。点击Save按钮，将文档发布到开发者门户。

图1：将OpenAPI规范文件上传到
API Connectivity Manager以创建文档

确保版本控制正确

版本变更必须始终谨慎处理。在微服务环境中尤其如此，因为许多服务可能会与同一个API交互。如果未谨慎引入新版本并停用旧版本，一项破坏性变更就可能导致数十个微服务发生级联中断。

NGINX如何提供帮助：将OpenAPI规范文件与API Connectivity Manager结合使用，可轻松对API进行版本控制。除了设置版本号外，还可以为每个版本提供文档，并管理其状态（最新、有效、已停用或已弃用）。

要发布API的新版本，请点击左侧导航栏中的“Services”。在表格中点击Workspace名称，然后在打开的页面中点击Environment名称。接下来，点击“+ Add Proxy”按钮。您可以在此上传OpenAPI规范，设置基础路径和版本以创建URI（例如/api/v2/），并输入其他重要元数据。点击“Publish”按钮，保存并发布API代理。

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

图 2：在 API Connectivity Manager 中管理活跃的 API 版本

生成API凭据

要提高API的采用率，需要尽可能简化API使用者的入门流程。用户找到所需的API后，需要通过一种安全的方式登录开发者门户并生成凭据。这些凭据可授予用户访问API功能的权限。通常，建议实施自助式工作流，让用户能够自行注册。

NGINX 如何提供帮助：API Connectivity Manager 支持开发者门户上的自助式 API 工作流，用户可自行生成用于访问 API 的资源凭据。可在门户上使用API 密钥或HTTP 基本身份验证来管理资源凭据。还可在开发者门户上启用单点登录（SSO），以保护访问安全，并允许通过身份验证的 API 使用者管理资源凭据。

要在开发者门户上快速启用SSO，请点击左侧导航栏中的“Infrastructure”。然后点击表格中的Workspace名称（在图3中，该名称为team-sentence）。

图 3：Infrastructure 选项卡中的 Workspace 列表

在“Workspace”页面的表格中，单击要配置的“Environment”名称（在图 4 中为“prod”）。

图4：Workspace中的Environment列表

在Developer Portal Clusters部分，单击当前所用开发者门户对应的…图标（位于Actions列），然后从下拉菜单中选择Edit Advanced Config。在图5中，唯一的Developer Portal Cluster为devportal-cluster。

图5：为Developer Portal Cluster选择Edit Advanced Config选项

接下来，单击左侧导航栏中的 Global Policies。要配置 OpenID Connect Relying Party 策略，请单击该策略所在行的“…”图标（位于“Actions”列），然后从下拉菜单中选择 Edit Policy。有关详细信息，请参阅《API Connectivity Manager 文档》。

图 6：配置 OpenID Connect Relaying Party 全局策略以启用单点登录