API Catalog SEO：让 AI Agent 发现你的公开 API

一个 API 产品的文档可以写得很好，却依然很难被发现。

文档可能放在另一个域名，OpenAPI 描述藏在代码仓库里，认证规则出现在价格页，而真正有用的 endpoint 只在一篇教程中被提过一次。

对人来说，这是不方便；对需要判断网站是否有真实可用能力的 AI agent 来说，这会制造大量不确定性。

API Catalog 要解决的正是这个问题。它不是 AI 搜索排名技巧，而是给真正提供公开 API 的发布者使用的机器可读目录。

这篇是 面向 AI Agents 的 Link Headers 的实操延伸，也和 MCP Server Card for Product Websites 及更大的 Agent SEO audit 集群相连。

API Catalog 是什么

RFC 9727 定义了 api-catalog link relation，以及可发现的 /.well-known/api-catalog 路径。

它是一个 Linkset 文档。它的职责是在一个可预测的位置列出发布者的 API，让客户端无需猜 URL 或抓取整套文档，就能开始发现 API 能力。

API Catalog 不等于：

资源	它解决什么	它不能替代什么
API Catalog	列出可用 API，并链接到其相关资源	Endpoint 文档和访问控制
OpenAPI 描述	说明操作、参数、响应和 server	一个汇总所有公开 API 的顶层目录
开发者门户	帮人类评估和学习 API	机器可读的 discovery 入口
MCP Server Card	帮 agent 了解 MCP server 的能力和边界	HTTP API 清单
llms.txt	提供网站的可读精选地图	API contract、认证规则或 endpoint 元数据

对于有真实对外能力的应用，这些资源可以彼此配合。对于普通内容站，则不应该为了看起来更“agent-ready”而硬造一套。

先做适配判断

只有以下问题的答案都是“是”，才值得发布 API Catalog：

• 组织是否发布了允许第三方发现的一个或多个 API？
• 每个被列出的 API 是否有稳定 endpoint 或 service URL？
• 能否提供最新的文档、认证要求、使用政策和版本信息？
• API 变化时，是否有人负责移除已废弃目录条目？

如果答案是否定的，就停在这里。先把 sitemap、内链、Technical SEO 和可读文档做好。

指向私人实验、无人维护 endpoint 或营销页的 API Catalog，比没有目录更糟。它浪费发现成本，也让 agent 后续验证变得更困难。

RFC 9727 的最小实现模式

RFC 9727 要求支持 well-known 路径的发布者让 GET /.well-known/api-catalog 返回 API Catalog 文档，并在 HEAD 请求中返回 Link response header。目录使用 RFC 9264 定义的 Linkset JSON media type。

一个精简目录可以这样写：

{
  "linkset": [
    {
      "anchor": "https://api.example.com/.well-known/api-catalog",
      "item": [
        {
          "href": "https://api.example.com/v1/catalog",
          "title": "Product catalog API",
          "type": "application/json"
        },
        {
          "href": "https://api.example.com/v1/audit",
          "title": "Site audit API",
          "type": "application/json"
        }
      ]
    }
  ]
}

服务端应返回 Linkset content type，例如：

Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"

接着从有意义的页面暴露 discovery relation，例如 API host、开发者门户或对应产品域名：

Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json"

具体部署布局可以不同。重要的是 URL 能访问、目录描述真实 API，且发布者能够持续维护。

给目录补足可验证的上下文

目录不应该只是几个模糊名称。发布前，请建立一份开发者和 agent 都能验证的 API 清单：

需要确认的字段	为什么重要
稳定 endpoint 或 API root	让客户端分辨真实服务与文档页
OpenAPI URL 或人类可读文档	解释操作、输入、响应和限制
认证方式	避免对匿名访问做出不安全假设
Rate limit、价格和条款	帮助客户端判断使用是否被允许且可行
版本与弃用策略	避免 agent 选择旧 API
负责人和复查日期	让过期条目可追溯

适合时，可以用 describedby、service-doc 或 service-desc 关系，把目录条目指向支持文档。relation 值要准确，不要把所有不相关资源都标成 API。

这也是 Auth.md 与 OAuth Metadata 和 Agent Skills Index 可能出现的位置。它们分别解决受保护资源 discovery 与能力说明，不会替代清晰的 API 文档。

四步发布工作流

1. 确认适配。 只列出明确对外或对获授权第三方开放的 API。
2. 盘点事实。 为每个 API 记录 endpoint、文档、OpenAPI URL、认证、限额、版本、负责人和复查日期。
3. 发布 discovery。 在 /.well-known/api-catalog 提供 Linkset，返回正确 content type，并在适合的页面加入 api-catalog Link header。
4. 上线后验证。 检查状态码、headers、JSON 结构、链接 URL，以及文档是否仍描述线上服务。

这个工作流刻意偏运营。它让团队获得一个可维护的资产，而不是一次性的元数据文件。

测试线上部署

从 API host 开始：

curl -I https://api.example.com/.well-known/api-catalog
curl https://api.example.com/.well-known/api-catalog
curl -I https://api.example.com/

逐项确认：

• GET /.well-known/api-catalog 成功返回。
• Response 声明 application/linkset+json，使用时带 RFC 9727 profile。
• HEAD 请求按标准返回 api-catalog Link header。
• 每个 item URL 都指向真实 API，而不是失效 endpoint 或普通落地页。
• 对应 OpenAPI、文档、认证与条款页面仍与线上 API 一致。
• 已废弃 API 已移除，或按照发布者的版本策略清楚标注。

可用 Bot Simulator 和 Agent SEO Audit 检查更广泛的 discovery surface，但不要把 audit 分数当作 API 安全或可用性的证明。API 行为仍需要产品和安全测试。

API Catalog SEO 能做什么、不能做什么

API Catalog 可以降低 discovery 过程中的不确定性，让开发者、客户端、crawler 或 agent 更容易找到开始评估公开 API 的正确位置。

它不能：

• 保证 Google 收录、排名、AI citation 或 agent 采用；
• 把私有 API 变成公开 API；
• 替代 OAuth、scopes、consent、rate limiting 或 abuse control；
• 替代 OpenAPI、开发者文档或稳定的版本策略；
• 单独让纯内容站变得更有用。

Google 当前的 生成式 AI 搜索优化指南 依然以正常搜索质量和技术资格为基础。把 API Catalog 放在它狭窄而诚实的位置：API discovery。

Fennec 用户的下一步

如果产品确实有公开 API，可以按这张短清单推进：

1. 盘点你准备长期支持的 API。
2. 确认每个 API 都有稳定 endpoint、最新文档和明确访问规则。
3. 按 RFC 9727 发布并验证 /.well-known/api-catalog。
4. 从相关 API host 或开发者门户用 rel="api-catalog" 链接它。
5. 用 Agent SEO Audit 检查公开 discovery surface，并用 Technical SEO 保持网站可抓取。

如果网站没有 API，就先维护更简单的 discovery 基础：sitemap、准确内链、有用内容，以及真正服务读者或客户端的机器可读资源。

Sources

• IETF RFC 9727: api-catalog
• IETF RFC 9264: Linkset
• IETF RFC 8288: Web Linking
• OpenAPI Specification
• Google Search Central：优化生成式 AI 搜索功能

问答

发布 API Catalog 会提升 Google 排名吗？

不会。它不承诺也不暗示排名收益。API Catalog 是给拥有真实公开 API 的发布者使用的 API discovery 标准，不能替代可抓取性、有用内容或正常 SEO。

纯内容网站需要 API Catalog 吗？

通常不需要。内容站应先维护 sitemap、内链、可抓取性、有用页面，以及真正对读者或机器有用的可读资源。

OpenAPI 文件和 API Catalog 是同一个东西吗？

不是。OpenAPI 描述一个 API 的操作、参数和响应；RFC 9727 API Catalog 是可发现的 Linkset 目录，用来列出发布者的 API，并引导到相关文档和描述。