API 管理平台管理什么
API 管理包括接口登记、文档维护、调用授权、使用追踪,以及变更和下线。API 管理平台把这些工作集中到一个系统中,具体覆盖哪些环节,需要逐项确认。
当多个团队重复整理文档、合作方靠人工申请密钥,或接口收费却难以核对用量时,就适合评估 API 管理平台。技术负责人确定接入需求,采购负责人确认交付和验收范围。
下文为通用架构和验收示例,预期结果未经产品实测;YesAPI Pro 的交付范围见所链接的套餐说明。
四类工具的职责对照
先按团队需要的工作判断工具类别。
| 工具类别 | 主要负责的工作 | 常见使用者 | 选型时重点验证 |
|---|---|---|---|
| 接口文档与研发协作工具 | 接口设计、调试、测试与文档协作 | 开发、测试、对接团队 | 请求和响应是否一致,变更后文档如何同步,现有描述文件能否导入导出 |
| API 网关 | 在请求入口处理路由、身份校验、限流等运行策略 | 平台与运维团队 | 请求实际经过哪里,策略如何生效,上游故障如何定位 |
| API 开发平台 | 编写或配置接口逻辑,将业务系统与数据源组织为 API | 后端与数据开发团队 | 数据源、参数校验、业务逻辑和发布方式是否符合项目需求 |
| API 开放运营平台 | 组织开发者接入、应用申请、接口授权;按业务需要增加套餐、订单和结算 | 开放平台与运营团队 | 开发者能否完成接入,权限是否执行,购买和用量能否核对 |
这些类别可以重叠:开发平台可能提供文档,网关可能配套开发者门户,开放平台也可能处理请求。比较时应记录具体模块和执行位置。
OpenAPI 规范定义了与语言无关的 HTTP API 描述方式,供文档、代码生成和测试工具使用;权限与流量策略仍需在运行时执行。
按业务需求选择建设路径
| 当前需求 | 先完成的工作 | 后续阅读与产品方向 |
|---|---|---|
| 内部团队协作 | 统一接口目录、负责人、文档和变更流程;有运行流量治理需求时再评估网关 | 参考 Java 企业版的架构与能力;需要补充接口开发时阅读数据库转 API 实践 |
| 向合作方开放接口 | 建立开发者入口、应用申请、接口授权、凭证停用和接入文档 | 查看 API 开放平台能力;可评估 Java 企业版或 PHP 标准版 |
| 自营 API 收费 | 在开放接入基础上确定收费规则,串起套餐、订单、支付、计量和账单核对 | 阅读 API 计费模式与验收清单;评估 Java 企业版或 PHP 旗舰版 |
| 第三方服务商入驻 | 增加服务商身份、接口上架、成本与收益、结算和提现流程 | 查看多商户平台能力与 PHP 多商户版 |
YesAPI Pro 的 Java 三个套餐均列明 API 计费;PHP 标准版提供接口开放与管理,旗舰版增加收费,多商户版增加第三方服务商模块。根据技术栈、源码需求和交付条件选择套餐,具体范围与价格查看版本与价格。
文档、网关与开放平台可以一起使用
已有网关和文档工具的企业,可以在现有架构上补充开放流程:
设计与发布:
研发协作工具 -> 接口契约与测试 -> 业务 API / 开发平台
开放运营平台 -> 开发者、应用、接口授权 -> 对接接入层策略
实际调用:
调用方 -> 接入层(网关、鉴权等) -> 业务 API -> 业务数据
| |
+---- 日志与用量记录 ---+
|
监控 / 统计 / 如需计费则核对账单
开放平台的接口授权,需要在调用链路中执行。团队应指定身份来源、权限检查位置、策略更新方式和计量记录来源。浏览门户和调用业务接口可以走不同链路。
API7 的职责说明把网关放在流量入口,也说明相关工具可以组合。项目应据自己的请求链路,核对新增平台与现有网关的协议、身份和策略对接方式。
采购时比较这八项,并要求现场验证
| 比较项 | 需要问清的内容 | 可执行的验证动作 |
|---|---|---|
| 接口与文档 | 导入格式、参数与错误说明、版本和下线流程 | 用现有描述文件导入一个接口,修改一个字段,核对文档与实际响应 |
| 开发与系统接入 | 可连接的数据源、已有接口协议、复杂逻辑处理方式 | 携带脱敏接口和查询需求,演示从配置到调用;记录需要额外开发的部分 |
| 身份与权限 | 开发者、应用、管理员各自的权限,凭证失效和数据隔离 | 创建两个应用,交叉访问同一资源,再停用其中一个应用并复测 |
| 可观测性 | 调用日志、错误与耗时、应用用量、敏感字段处理 | 制造参数错误与上游超时,按应用和请求线索定位;核对日志保存与访问范围 |
| 计费与运营 | 成功、失败、超时与重试如何计量,套餐与订单如何关联 | 用一小组已知请求核对用量和账单,再验证重复支付通知与异常处理 |
| 部署与运维 | 环境依赖、网络要求、备份恢复、升级与回退责任 | 逐项核对部署清单,在测试环境演示备份恢复,确认维护由谁负责 |
| 源码与授权 | 后端、各套前端和测试代码的交付范围,主体及项目限制 | 对照文件清单验收;采购源码时按交付说明在独立环境构建;把客户交付与 OEM 权限写明 |
| 服务与总成本 | 实施、定制、第三方服务、售后期限、后续升级和源码同步 | 索取逐项报价与责任清单,确认哪些包含、哪些另计,以及问题处理入口 |
为候选方案记录支持情况、验证证据、额外交付工作与负责方。演示中未确认的项目,继续安排验证或列为交付任务。
私有部署和源码交付要分别核对。Java 旗舰版私有部署交付安装包,不含前后端源码;需要源码可评估 Java 源码版或招投标版。PHP 标准版交付后端源码与前端编译运行代码,不含 Vue 前端源码。进一步参考源码与授权条款与私有部署方案。
用合作方订单查询走一遍演示
假设企业向合作方 A、B 免费开放订单查询,双方只能读取自己的订单。可以按以下步骤演示候选方案。
- 准备接口与数据。 使用归属 A、B 的脱敏订单,登记接口负责人、路径、参数、响应和错误说明。可用已有服务验证;需要生成接口时参考数据库转 API 流程。
- 核对文档与调用。 导入或录入接口描述,发起正常和参数错误请求,核对实际返回;排除不应对外显示的内部字段。
- 建立调用身份。 为 A、B 分别创建应用、配置访问范围,记录凭证申请、发放、授权和停用流程。
- 验证接口权限与数据归属。 A 应能读取自己的订单;A 读取 B 的订单应被拒绝或按约定隐藏资源。再取消 A 的接口权限、停用其凭证并复测,确认服务端执行了相应限制。
- 制造故障并定位。 在测试环境模拟上游超时,核对调用方错误和后台排错线索;检查日志是否暴露凭证或订单敏感信息。
- 变更与退出。 新增可选响应字段,检查文档更新与旧调用方兼容情况;停用 B 应用并复测旧凭证。需要收费时追加购买、用量与账单核对。
OWASP REST 安全建议要求使用 HTTPS,并在每个受保护端点执行访问控制。验收时应检查实际请求结果。
保留脱敏请求、响应、配置和待解决项,作为采购验收清单的依据。
常见采购问题
已经有网关和文档工具,还需要开放平台吗?
现有系统满足需求时可以继续使用。合作方需要自行注册、申请应用或购买套餐时,再评估开放运营平台能补上哪些流程,并核对身份和权限对接。
API 开放一定要建设收费商城吗?
可以先免费开放,解决文档和权限。PHP 标准版面向接口开放;收费需求可评估 Java 企业版、PHP 旗舰版或多商户版,按计费清单验证规则。
私有部署和永久授权是否允许向其他客户转售?
同一客户主体内不限项目数量,仍有主体限制。向客户交付、OEM、源码移交和联合投标需取得合同授权,套餐使用范围见授权说明。
准备一个脱敏接口、目标调用方、现有鉴权方式、收费与源码需求后,可预约演示,按上述步骤验证并记录结果。
参考资料
以下为本文引用的官方资料。文中的通用示例与产品套餐能力分别说明。
接下来,如何选型?
先确定平台职责,再比较版本。
需要集中组织接口、开发者与权限时,从企业 API 管理方案开始,再按技术栈和交付范围选型。
- 带上现有接口目录、调用方与权限流程。
- 区分网关、文档工具和开放平台各自负责的工作。