什么是 API 成熟度模型？

部分 API 成熟度框架侧重特定维度，如安全性、可发现性、可维护性或平台工程。包括 Kong、Tyk 和 Curity 在内的 API 管理供应商，均提供与其解决方案相适配的 API 成熟度模型，帮助客户衡量自身在采用这些平台方面的进展。其他模型则适用范围更广，可应用于任何协议或架构。

应用程序编程接口 (API) 作为连接不同服务与应用的关键纽带，是互联网的重要支柱。它帮助开发者直接调用第三方技术和数据源，无需从零开始构建。API 还能实现组织内部资源、数据、安全及治理的集成，从而简化内部部署流程并促进跨团队协作。多个 API 可与程序库、用户界面工具及其他组件打包，形成软件开发工具包 (SDK)，帮助开发者快速可靠地构建标准化应用。

API 成熟度模型通过识别和描述具体的结构技术创新、技术演进以及战略性最佳实践，助力组织开发更成熟稳健的 API 系统，从而提升效率、安全性与互操作性。这些模型为组织加速 API 开发提供了路线图，帮助其确定优先推进的创新方向。

Richardson 成熟度模型是引用最广泛的框架之一，它通过四个成熟度层级评估 API 对 RESTful 原则的遵循程度，其中最高层级代表完全符合 REST 架构风格的系统。

2000 年，计算机科学家 Roy Fielding 提出  REST 架构风格，倡导统一接口、客户端-服务端解耦、无状态性、可缓存性和分层系统等特性。这些功能共同作用，可在组织内部提升可扩展性、效率和灵活性；若在更大范围实施，还能为构建更开放、更具韧性和更安全的互联网作出贡献。现代 REST 架构常通过 HTTP 传输信息，并采用人类可读的 JSON 格式组织数据，当然也可使用其他协议和格式。

2008 年，软件工程师 Leonard Richardson 基于这一框架提出模型，明确了组织可通过实施具体技术改进来增强 REST API 设计的适应性与弹性。Richardson 成熟度模型 (RMM) “鼓励将 URI、HTTP 和超媒体（即 HTML）这三种 Web 技术视为独立技术而非捆绑组合，”Richardson 在接受 IBM Think 采访时表示。该框架展示了逐步实施各项技术的实际效益，“鉴于这些技术已广泛存在、备受青睐，且获得所有编程语言的普遍支持。”

Richardson 成熟度模型优先关注资源实现，遵循 REST 通用原则为每个资源分配独立 URI——该原则建议为每个资源赋予唯一标识。RMM 同时倡导使用响应文档（捕捉 API 当前状态）而非描述文档（静态呈现 API 在单一时间点的预设描述）。该模型主要适用于基于 HTTP 的 Web 应用，但作为概念框架，也可应用于物联网网络、数据管道等其他场景。

Richardson 成熟度模型通过四个层级区分不同成熟度，涵盖从非 REST 架构到完全 REST 架构的演进过程。

第零级代表非 REST 架构设计，其特征是使用单一端点（如“/api”）和单一指令（通常为 POST）。该层级虽易于实现，却未能发挥 HTTP 最强大的特性（包括动词、URI 和状态码）。此时 HTTP 仅作为传输机制，所有操作细节均需附加在消息体中。

由于基于 XML 的远程过程调用 (RPC) 模式历来采用此方法，批评者戏称为“POX 沼泽”（纯旧式 XML）。其症结在于缺乏结构化设计，服务、功能与数据之间界限模糊，极易导致系统臃肿和紧密耦合。在第零级，API 无法识别或暴露可发现资源，迫使调用方必须预先知晓可用内容。开发者可能在扩展、版本控制和故障排查方面举步维艰，因为单端点无法实现信息自述。

第一级引入多 URI 机制，每个 URI 可代表不同资源。但该层级仍沿用单一 HTTP 动词（通常为 POST）。客户端不再调用泛化的“/api”端点，转而调用对应特定资源的端点——例如电商场景中的 “/products”“/carts” 或 “/invoices”。不过客户端通常仍需通过请求体传达操作意图，而非使用 HTTP 预定义的动词集。

这种设计在资源之间建立了更清晰的界限，减少了客户端对可用资源的认知歧义。但由于调用 URI 缺乏标准化格式，开发者仍易混淆可执行的操作类型。随着时间推移，第一级架构会逐渐暴露弊端——实践中开发者可能为单个动作创建独立端点（如 “/productsUpdate” 或 “/productsDelete”）。这种方法可能导致 URI 数量不断堆积，加大版本更新与管理的难度。

此外，尽管资源被赋予独立标识符，但端点本身无法揭示可执行的操作，使得开发者更加依赖外部 API 文档。

第二级引入了 HTTP 方法，通过标准化动词集实现数据与服务交互。典型配置中，客户端可通过增删改查四类基础指令在每个端点执行差异化操作。API 调用时还可通过请求头传递内容类型、条件约束、授权凭证等补充信息。

相较于前两级，这种模式通过显式暴露 API 功能边界和交互规范，显著提升了系统效率与结构化程度。但 API 仍无法实时传递能力信息——用户需通过外部开发者门户了解接口详情，降低了可发现性。这种静态设计若遇 API 文档与功能脱节，将导致认知偏差。

当前多数企业的 API 生态系统运行于第二级，因其在可预测性、效率与可访问性间取得平衡。该层级还能充分利用 HTTP 的基础设施特性（如将高频资源缓存至本地实现快速调用），带来显著的性能提升。

第三级引入 HATEOAS（超媒体作为应用状态引擎）机制。当客户端发起 API 调用时，系统将像现代浏览器那样，动态返回包含操作选项与关联术语的响应列表。这些交互要素通过带内传输实现，开发者无需查阅外部文档即可获知。基于超媒体的架构还能增进互操作性，因为外部客户端无需事先学习使用方法即可轻松访问服务。

但超媒体控制也带来了运行时复杂度：“客户端不仅要能按预设程序响应，更要具备解析服务端文档的能力，通过理解文档内容自主决策下一步请求。”Richardson 阐释道。

由于超媒体的动态特性，构建和维护此类能力的成本与耗时较高。API 需通过返回包含后续操作的链接集来响应客户端请求，这增加了运行负担。此外，许多客户端平台并不支持超媒体，因此当组织采用 HATEOAS 时，外部用户可能需要先寻找兼容工具才能访问这些服务。

Richardson 表示，当前 HATEOAS 最常被图书馆、非营利机构、科研院所、市场联盟或新兴企业（试图颠覆行业的组织）使用，因其倡导开放性与互操作性。在内部应用中，超媒体同样能发挥实效——即便对 API 生态系统毫无了解的用户，也能轻松发现 API 及其操作。部分公司在成长期可能开放超媒体 API，待产品实现商业化后则会限制访问。

业界正逐步转向 GraphQL 和 gRPC 等替代方案以满足特定场景需求。根据 Postman《API 现状报告》，尽管 93% 的开发者表示仍在使用 RESTful Web 服务，但已有三分之一采用 GraphQL，14% 使用 gRPC。GraphQL 能智能地从多个微服务（甚至部署于不同环境的服务）获取请求并整合为单一响应，从而提升效率并避免资源过度或不足配置。而 gRPC 则适用于流媒体、遥测等以高性能和低延迟为核心诉求的场景。

虽然 GraphQL 和 gRPC 无法复现超媒体的动态特性，但这两种架构能更精准地解决效率与模式管理方面的痛点，促使部分组织优先采用这些方案而非完整实施超媒体控制。

在 Richardson 成熟度模型中，API 成熟度层级的跃升往往伴随着设计与技术的双重挑战。实现从第零级到第一级（多 URI 支持）再到第二级（多 HTTP 方法支持）的演进，通常需要重构服务端代码。这涉及路由规则、数据库交互、测试用例、接口文档及控制器的全面更新。

组织可先系统梳理现有端点，筛选可改造为 RESTful 约束的接口，并规划所需资源与操作类型。开发者可在现有系统基础上构建新版本，确保过渡期间客户端调用不受影响。完善的错误代码体系能帮助用户无需查阅大量文档即可掌握新 API 端点调用方法并自主排查故障。

与专注于 RESTful 系统技术实现的 RMM 不同，组织级模型以更宏观的视角，助力企业围绕一致性、资源优化与适应性等共同原则形成战略协同。尽管战略框架因组织而异，但常见模式包含四个层级：

在基础级或临时级 API 生态中，组织应对的是当务之急，而非在统一的 API 开发框架下工作。开发者根据需求随意创建或废弃 API，因缺少集中管控易导致系统失序，引发治理、安全与可观测性问题。由于无法洞悉 API 运行状况，团队难以有效配置资源或规划未来发展。

标准化 API 生态建立统一的文档规范、命名规则、错误代码与设计模式。可通过 API Gateway 实施认证、授权等集中化 API 安全管控。开发者可在组织治理架构内自主增删维护 API，并实现组件复用与灵活适配。通过开发者门户与集成化引导流程，客户端能轻松发现并了解可用服务，显著提升 API 采用率。

但此阶段因缺乏有效的 API 性能与安全监控机制，团队可能难以全面掌控生态状况。例如，组织可能对特定 API 集群的安全漏洞、版本错误或认证异常浑然不觉。

受管级框架通过遥测数据、关键绩效指标 (KPI) 及其他度量标准，实现对 API 性能更精细的监控。例如，当客户端遭遇频繁 API 停机时，监控系统可向开发者发出警报，并帮助分析出根本原因——无论是服务器过载、网络中断、代码失配还是其他问题。

受管级生态还可能配备更高级的 API 治理架构，既保留团队自主权，又让利益相关方清晰了解各自负责管理的 API 范围。此外，受管级生态引入正式的生命周期管理流程，对 API 的设计、开发、维护、版本控制到退役全程进行监控。但在此阶段，组织可能仍未形成统一认知，难以明确 API 管理如何服务于更广泛的业务目标。

优化级或战略级框架将治理、标准化、生命周期管理、度量标准、安全最佳实践与长期业务规划相融合。通过对整个网络的全局掌控，组织能高效扩展资源、动态响应市场变化。API 不再被视为单纯的技术组件，而是可服务于更广泛业务目标的战略工具。战略级框架助力组织制定前瞻性路线图与规划策略，从而加速创新、提升运营效率。

组织可针对特定痛点或运营重点定制 API 成熟度模型。常见方向包括：

此类成熟度模型聚焦 API 设计原则，如采用特定协议、实践和标准以提升用户体验。RMM 是基于设计的框架典范，但其他模型可能侧重 GraphQL、gRPC 等不同架构风格。

此类治理模式关注组织对 API 生态的管控与监督能力。在最高层级，组织能在保持利益相关方自主权的同时，确保高合规性、数据质量和安全性。

基于治理的框架还会考量 API 生态执行机制的质量，例如是否纳入自动化检查与验证流程。此类模型通过将 API 分配给具体团队，实现所有 API 责任到人。

安全导向型成熟度模型用于评估 API 网络对安全最佳实践的遵循程度。在初始阶段，组织可能依赖 API 密钥或基础 HTTP 认证，此类方式既缺乏精细化管控，又易泄露风险。进阶系统可引入基于令牌的认证授权机制及零信任访问。最高级框架则遵循身份和访问管理原则，例如采用 OAuth 和 OpenID Connect (OIDC) 授权协议。

API 文档是指导开发者使用和集成特定 API 的技术指南。文档可包含教程、代码示例、版本说明及可接受的调用参数。

初期组织可能缺乏标准化的文档创建与维护流程，导致开发者难以了解各 API 的功能边界。较高级别可引入 OpenAPI 规范 (OAS) 或 API 蓝图等标准化格式来描述 API 规范。成熟的 API 框架还可能融入自动化机制，确保每次部署时文档同步更新。

可观测性导向型成熟度模型帮助组织追踪微服务间数据采集机制的成熟度。基础系统可通过遥测与度量指标发现错误，但无法识别长期数据趋势。

更复杂的平台能主动监控延迟、请求速率等相关指标，帮助组织预先应对停机、失配等问题。在最高层级，组织能够识别高层次数据模式，并生成可指导未来 API 开发的切实可行的洞察。