API Catalog — /.well-known/api-catalog (RFC 9727) và Link header

Tệp (RFC 9727 §4, Phụ lục A):

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

{"linkset": [
  {"anchor": "https://example.com/api",
   "service-desc": [{"href": "https://example.com/openapi.json", "type": "application/json"}],
   "service-doc":  [{"href": "https://example.com/docs/api", "type": "text/html"}],
   "status":       [{"href": "https://example.com/api/health"}]}
]}

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

Link header (RFC 8288) mang cùng con trỏ đó trên mọi trang: Link: </.well-known/api-catalog>; rel="api-catalog". Chỉ các quan hệ đã đăng ký mới có nghĩa với agent — api-catalog, service-desc, service-doc, describedby, hoặc alternate dạng text/markdown. preconnect, preload và shortlink là gợi ý cho trình duyệt và CMS; các tên tự đặt như mcp-server hay agent-skills không có trong danh mục IANA.