让 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 的规划和设计往往是多人协作的，出于这样的需求，市场上也诞生了很