让 API 管理效率更进一步的 API7 DevPortal

作者张超，API7 Cloud 产品负责人，Apache APISIX PMC 成员。

原文链接

当今计算机世界，人们早已习惯使用 API 在软件之间完成信息的交换，不论是你在手机上查看天气信息、查看微信朋友圈的动态、亦或是和 ChatGPT 交互，其实都是通过 API 来完成的。从定义上来说，API 是一组通信的约定，它规定了你（或者软件）如何与目标软件服务交互。

API 全生命周期管理

随着业务的增长，公司的 API 数量往往会越来越多，如果不对这些 API 进行管理的话，通常就会带来混乱，比如人员协作成本增高、服务稳定性以及安全性受到挑战。因此，人们提出了所谓 API 全生命周期管理的概念，以便可以更好地管理 API。我们可以将一个 API 从设计开始，到最后下线完成使命这个过程分成不同的阶段。通常来说，我们会将 API 生命周期分为规划和设计、实现、管理三个大阶段。

规划和设计

作为工程师，我们总是强调在编码前先进行方案的设计。API 也不例外，我们需要根据业务明确一个 API 的功能目的，然后结合相关技术栈，将业务语言翻译成技术语言。通常来说，API 规划和设计是围绕着文档进行的，以 RESTful API 为例，API 文档中应该包括如下信息：

• API 功能描述

• API 对应的 URL

• HTTP 请求方法

• 请求参数、请求体、请求头的描述（以及约束）

• 可能的响应状态码和响应体的描述

关于如何撰写一份合理的 API 文档，人们也开展过很多的研究，目前比较流行的是按照 OpenAPI Specification V3 进行 API 文档的设计。

此外，在真实世界里，API 的规划和设计往往是多人协作的，出于这样的需求，市场上也诞生了很多专注于 API 规划和设计的平台，比如 Postman。这些工具允许用户以可视化的方式设计 API，同时能满足协作的需求（也许是在它们的付费版本中），并且允许用户将 API 以某种格式进行导入导出，以便进行迁移。

实现

API 设计完毕后，工程师们就可以着手开发了。工程师可以选择自己擅长的、或者是组织要求的技术栈实现 API。并且在开发后为 API 进行测试，比如工程师可以为 API 添加端到端的测试、或者请求 QA 团队的测试。实现完毕后，工程师即可着手准备 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 的问题。我们不妨来看下，如果想让一个外部的开发者调用你的 API，需要解决哪些问题？

第一个问题是，如何让外部的开发者查看到 API 的信息，包括 API 的接入地址、API 的描述、参数约束、使用示例等。这些详细信息能够有效地帮助到外部开发者去理解并使用 API；第二个问题是，作为 API 的“生产者”，我们往往不希望谁都可以来调用我们开发的 API，即我们希望对 API 进行有效地保护，因此外部的开发者应该仅在获得了有效的 API 凭证以后，才能真正使用 API。更重要的是，我们希望 API 的“消费”应当是尽可能自助的，从而减少沟通协作带来的成本。

为了优化 API “消费”这个环节，人们提出了开发者门户这个概念，借此来解决上述的问题。

开发者门户

开发者门户通常分为管理端和开发者端两个站点。管理端的用户为 API“生产者”（下面称为管理员），开发者端的用户为 API“消费者”（下面称为开发者）。

开发者门户管理端最核心的功能在于让管理员高效控制 API 的发布和下线，仅发布后的 API 在开发者端站点可见。当然，管理员也可以为发布的 API 添加一些策略，例如限制访问 QPS、要求鉴权等来保护发布的 API，此外，管理员还可以在这里对来自开发者端站点的请求进行审批，包括开发者账号注册、开发者希望订阅某个 API 等。某些开发者门户产品允许管理员定制开发者端站点的样式，包括替换 Logo、修改标语等。

而开发者端是为 API“消费者”准备的，在开发者端可以看到所有由管理员发布后的 API（以及它们的细节信息），并且向管理员申请 API 的订阅；开发者可以为已经订阅的 API 创建访问所需要的凭证信息，并通过查看 API 文档来了解如何集成。

一些开发者门户还会集成 API 调用分析，比如在管理端以开发者的视角展示过去一天某个 API 的调用量、延迟情况等，这些数据能够成为未来迭代和优化 API 的决策依据，帮助 API 变得更加完善。

随着 API 生态系统的完善，API 货币化这一概念也逐步被人们重视起来，而开发者门户则成了进行 API 货币化的良好工具，比如管理员可以为 API 创建多个订阅计划，按照不同的配额进行差异化收费，亦或是根据 API 调用次数来进行按需付费。

即将推出的 API7 DevPortal

API7.ai 致力于为用户提供最好的 API 管理服务，为此，我们正在积极筹备一款开发者门户产品，我们称之为 API7 DevPortal。这款开发者门户产品将和 API7 Enterprise（企业级 API 网关产品，基于 Apache APISIX 构建）结合使用，并提供 API 订阅和开发者注册审批的功能。我们的客户可以轻松地将已经通过网关代理的 API 发布到开发者门户，进而让用户的开发者们在开发者端了解到 API 的详细信息。

未来，API7 DevPortal 将在两方面进行深入迭代，第一是和客户的审批流打通，部分客户公司有统一的审批平台，用来管理各类审批操作，我们希望在可以在不改变客户原有审批习惯的情况下让客户使用 API7 DevPortal；第二是支持 API 货币化，帮助我们的客户为不同的开发者提供不同层级的订阅服务，并且支持收费。我们将在不久后把 API7 DevPortal 推向市场，如果你对这款产品感兴趣的话，请点击这里联系我们。

总结

开发者门户在管理 API 消费的环节上起到了关键的作用，它帮助 “API 生产者们”有效地解决了 API 的集成问题，且没有安全等方面的牺牲，甚至能够帮助 “API 生产者们”进行变现。在 API 大行其道的今天，也许是时候考虑在你的团队里使用开发者门户了。

关于 API7.ai 与 APISIX

API7.ai 是一家提供 API 处理和分析的开源基础软件公司，于 2019 年开源了新一代云原生 API 网关 -- APISIX 并捐赠给 Apache 软件基金会。此后，API7.ai 一直积极投入支持 Apache APISIX 的开发、维护和社区运营。与千万贡献者、使用者、支持者一起做出世界级的开源项目，是 API7.ai 努力的目标。