API Catalog SEO

API Catalog SEO 是让明确对外开放的 API 更容易被开发者、搜索引擎和兼容 agents 找到并理解。真正有用的资产不是一张写着“我们有 API”的页面，而是与正确 interface description 和真实访问规则连接、有人维护的文档 surface。

OpenAPI 提供语言无关的标准方式，让人和计算机理解 HTTP API 能力；它不会自动完成发布、安全、收录或分发。

最低可用发布集合

资产	必须回答的问题
Overview page	API 面向谁，支持什么用户结果
OpenAPI description	Servers、paths、operations、parameters、schemas 与 security schemes
Authentication guide	凭据如何取得、限制 scope、轮换与撤销
Quickstart	使用安全测试路径完成一次完整 request 与 response
Error reference	Status codes、error objects、retry 行为与支持入口
Limits 与 pricing	Rate limits、quotas、成本边界与公平使用规则
Version policy	当前 version、兼容规则、弃用窗口与 changelog
Terms 与 data policy	允许用途、retention、privacy 与受限数据

如果 client 无法只靠公开材料完成一个安全 request，这个 catalog 就还没有准备好。

不要发明发现标准

先使用稳定、常规的链接方式：

• 从相关产品页和站点导航链接开发者文档。
• 为 API overview 和 specification 提供稳定 canonical URL。
• 面向公开收录的文档可以进入 XML sitemap。
• 从面向人的文档链接可下载 OpenAPI description。
• 只有语义匹配时才使用已注册 HTTP link relations。
• 只有适用规范定义或注册后才使用 /.well-known/ URI。

不要自行创建 well-known path 再声称 agents 都会发现。RFC 8615 规定的是 well-known URI 如何注册，并不会让任意路径自动互操作。

内容质量要求

高质量 API 文档不能只有自动生成的 endpoint 表：

1. 解释用户任务和每个 operation 的边界。
2. 提供使用明显虚构数据的真实示例。
3. 分开记录 authentication 与 authorization。
4. 在相关位置说明 failures、idempotency、pagination 与 retry。
5. 让 examples 与部署 version 保持同步。
6. 解释 data freshness 和容易误读的 fields。
7. 在 breaking changes 前发布 migration notes。

自动生成 reference pages 可以有用，但不能替代对 workflow、policy 与失败行为的解释。

与其他 Agent Surfaces 的区别

• HTTP service contract 使用 OpenAPI。
• 兼容 clients 需要 MCP tools 或 resources 时使用 MCP server。
• 需要打包可复用任务 instructions 时使用 Agent Skill。
• 已部署 A2A server 接收 agent-to-agent tasks 时使用 A2A Agent Card。

除非每个 integration 都真实存在、有人负责并经过测试，否则不要把同一个能力复制到所有格式。

验证清单

• 每个 documented operation 都存在于目标环境。
• Server URLs、authentication schemes、scopes 与 examples 仍然有效。
• 没有泄露 internal hostnames、secrets 或 private schemas。
• OpenAPI document 能按声明 version 通过验证。
• 新开发者无需未记录步骤即可完成 quickstart。
• Error 与 rate-limit 行为符合线上 response。
• Canonical、sitemap 和内链都指向首选文档 URL。
• Owner、changelog 和 deprecation dates 清楚可见。

完整实施指南见API Catalog SEO：AI Agents 如何发现公开 API。相关主题包括面向 AI Agents 的 Link Headers、Agent Skills Index 与 Auth.md 与 OAuth Metadata。

一手来源

• OpenAPI Specification
• RFC 8615: Well-Known Uniform Resource Identifiers
• IANA Link Relation Types