API Catalog (RFC 9727): cách để AI agent tìm thấy API của bạn

Câu trả lời ngắn: API catalog là một tệp JSON tại /.well-known/api-catalog liệt kê các API công khai của website: với mỗi API, bản mô tả máy đọc được (thường là OpenAPI), tài liệu và trang trạng thái nằm ở đâu. Chuẩn là RFC 9727 của IETF (tháng 6/2025). Tệp phải ở định dạng linkset và trả về với Content-Type: application/linkset+json. Thêm Link: </.well-known/api-catalog>; rel="api-catalog" vào phản hồi của trang để agent tìm thấy nó.

Vì sao AI agent cần catalog

Một AI agent đọc trang của bạn để trả lời câu hỏi. Nhưng khi người dùng nhờ nó làm việc gì đó — đặt chỗ, kiểm tra tồn kho, chạy một lượt quét — nó phải gọi API. Muốn gọi API, nó cần bản mô tả: endpoint nào, tham số gì, xác thực ra sao. Không có catalog, agent phải đoán URL như /api/docs hoặc đọc trang tài liệu HTML. RFC 9727 đặt bản đồ đó ở một chỗ cố định, giống robots.txt cho crawler hay llms.txt cho mô hình ngôn ngữ.

Tệp trông như thế nào

Đây là catalog của developers.cloudflare.com, chúng tôi tải ngày 22/10/2026:

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

{"linkset": [
  {"anchor": "https://developers.cloudflare.com/api/",
   "service-desc": [{"href": "https://developers.cloudflare.com/openapi.json", "type": "application/json"}],
   "service-doc":  [{"href": "https://developers.cloudflare.com/api/", "type": "text/html"}],
   "status":       [{"href": "https://www.cloudflarestatus.com/api/v2/status.json", "type": "application/json"}]}
]}

Các quy tắc trong RFC 9727 và RFC 9264 (định dạng linkset):

• linkset là thành phần duy nhất ở cấp cao nhất, và là một mảng. Mỗi phần tử có anchor (URL của API) và các quan hệ.
• Giá trị của mỗi quan hệ là một mảng đối tượng có href, kể cả khi chỉ có một liên kết.
• Quan hệ lấy từ RFC 8631: service-desc (OpenAPI hoặc mô tả máy đọc được), service-doc (tài liệu cho người), service-meta (chính sách, điều khoản), status (tình trạng). Catalog ngắn có thể chỉ liệt kê API bằng item; catalog lớn trỏ tới catalog con bằng api-catalog.
• Media type bắt buộc là application/linkset+json. APIs.json, một tệp OpenAPI trần hay JSON tự đặt chỉ được phục vụ thêm qua content negotiation, không được thay thế linkset.
• Yêu cầu HEAD tới đường dẫn phải trả về Link header có rel="api-catalog".

Link header: chỉ quan hệ đã đăng ký mới có nghĩa

Link header (RFC 8288) cho agent biết tài nguyên liên quan mà không cần phân tích HTML. Nhưng nhiều trang đã gửi Link header vì lý do khác: WordPress gửi rel="https://api.w.org/" và shortlink, theme gửi preconnect tới máy chủ font, framework gửi hàng loạt preload. Đó là gợi ý cho trình duyệt. Một agent tìm các quan hệ có trong danh mục IANA: api-catalog, service-desc, service-doc, describedby, hoặc alternate có type="text/markdown" (xem markdown negotiation). Tên tự đặt như mcp-server hay agent-skills không có trong danh mục.

Chúng tôi kiểm tra 8 website

Ngày 22/10/2026, chúng tôi chạy chính đoạn mã của bản quét CiteStat (packages/core/api-catalog.ts) trên trang chủ và /.well-known/api-catalog của 8 website:

Website	Link header cho agent	API catalog
developers.cloudflare.com	service-doc, describedby, alternate	Đạt — OpenAPI + tài liệu + trạng thái
blog.cloudflare.com	api-catalog	Đạt — 3 API, gồm một MCP server
vercel.com	api-catalog	Đạt — 1 API (item + OpenAPI + trạng thái)
docs.stripe.com	service-meta	Không có (404)
docs.claude.com	alternate (markdown)	Không có — đường dẫn trả về trang HTML
github.com	không có	Không có (404)
erpfit.com	không có	Không có (404)
citestat.com (trước sửa)	api-catalog (+ 2 tên chưa đăng ký)	Sai — JSON tự đặt, application/json

Hai điều đáng chú ý. Thứ nhất, Vercel liệt kê api.vercel.com hai lần: một lần bằng item, một lần làm anchor có mô tả. Đó vẫn là một API — bản quét đếm URL khác nhau, không đếm dòng. Thứ hai, docs.claude.com trả trang HTML 200 cho mọi đường dẫn lạ. Một bộ kiểm tra chỉ xem mã 200 sẽ nói "có catalog"; bản quét coi trang HTML là không có catalog.

Lỗi của chính chúng tôi

Đến ngày 22/10/2026, /.well-known/api-catalog của CiteStat là một JSON tự đặt ({"apis": [...]}) trả về với application/json. Không phải linkset, sai media type. Tệ hơn, bản quét của chúng tôi chấp nhận mọi JSON tại đường dẫn đó và gọi là "tương thích RFC 9727" — và chấp nhận mọi Link header, kể cả chỉ có preconnect. Chúng tôi đã sửa cả hai: catalog giờ là linkset hợp lệ (tài liệu API dạng HTML và markdown, cùng trang trạng thái), Link header chỉ còn quan hệ đã đăng ký, và một bài kiểm tra tự động chạy bộ chấm của bản quét trên chính catalog của chúng tôi. Catalog không có service-desc vì chúng tôi chưa xuất bản tệp OpenAPI — catalog không nên trỏ tới tệp không tồn tại.

Cách tạo catalog trong ba bước

1. Viết tệp. Một phần tử cho mỗi API: anchor là URL gốc của API, thêm service-desc nếu có OpenAPI, service-doc cho tài liệu, status nếu có trang trạng thái.
2. Phục vụ đúng media type. Với nginx, phần mở rộng .json sẽ làm sai Content-Type, nên đặt rõ:

   location = /.well-known/api-catalog {
     types { }
     default_type application/linkset+json;
     add_header Link '</.well-known/api-catalog>; rel="api-catalog"';
     alias /var/www/api-catalog.json;
   }

3. Thêm Link header </.well-known/api-catalog>; rel="api-catalog" vào phản hồi của trang chủ (hoặc mọi trang).

Không có API công khai? Bỏ qua bước này. Một catalog rỗng không giúp agent nào.

CiteStat kiểm tra những gì

Trong thẻ Agent Readiness, bản quét kiểm tra hai việc. Link header đạt khi có ít nhất một quan hệ dành cho agent đã đăng ký. API catalog đạt khi /.well-known/api-catalog (hoặc đích của rel="api-catalog") là linkset hợp lệ, đúng media type, có ít nhất một API. JSON tự đặt là lỗi mức trung bình; sai media type là mức thấp. Cả hai không đổi điểm SEO tổng. Gói miễn phí có 10 lượt quét mỗi ngày; nếu bạn quản lý nhiều website, xem bảng giá: gói Pro 500.000₫/tháng (chưa VAT) cho 100 lượt quét mỗi ngày.

Câu hỏi thường gặp

Website không có API có cần API catalog không?

Không. Catalog chỉ liệt kê API công khai. Website không có API thì không có gì để liệt kê, và một catalog rỗng hoặc bịa ra còn tệ hơn không có. Vì vậy bản quét CiteStat chỉ báo thiếu catalog ở mức thấp.

Có thể đặt tệp OpenAPI tại /.well-known/api-catalog không?

Không thay cho linkset. RFC 9727 bắt buộc catalog ở định dạng linkset (application/linkset+json). Tệp OpenAPI nằm ở URL riêng và được trỏ tới bằng quan hệ service-desc. Định dạng khác chỉ được phục vụ thêm qua content negotiation.

Link header nào có ích cho AI agent?

Các quan hệ đã đăng ký với IANA mà agent hiểu: api-catalog, service-desc, service-doc, service-meta, describedby, và alternate dạng text/markdown. preconnect, preload và shortlink là gợi ý cho trình duyệt. Tên tự đặt như mcp-server không có trong danh mục, nên agent không biết nghĩa của nó.

API catalog có giúp tăng thứ hạng Google không?

Không có tài liệu nào của Google nói vậy. Catalog dành cho agent và công cụ cần gọi API của bạn, không phải tín hiệu xếp hạng. Bản quét CiteStat tính nó trong thẻ Agent Readiness và không đổi điểm SEO tổng.

Nguồn: RFC 9727 (IETF, 6/2025) · RFC 9264 (linkset, 7/2022) · RFC 8631 (service-desc, service-doc) · IANA Link Relations (cập nhật 12/6/2026). Dữ liệu 8 website: tải ngày 22/10/2026.