---
title: "Trình tạo danh mục API cho /.well-known/api-catalog · DotsAgent"
description: "Tạo JSON linkset theo RFC 9727 cho /.well-known/api-catalog, liệt kê từng API cùng mô tả OpenAPI, tài liệu và trang trạng thái, kèm cấu hình nginx."
url: https://dotsagent.io/vi/agent-ready/api-catalog
---

RFC 9727

# Trình tạo danh mục API

Liệt kê các API công khai của bạn một lần để tạo JSON linkset theo yêu cầu của RFC 9727 tại /.well-known/api-catalog, kèm cấu hình nginx để phân phát tệp với media type phù hợp.

`/.well-known/api-catalog`

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

`nginx`

```
location = /.well-known/api-catalog {
    default_type application/linkset+json;
    add_header Link '</.well-known/api-catalog>; rel="api-catalog"';
    try_files /.well-known/api-catalog =404;
}
```

Tải tệp lên /.well-known/api-catalog và phân phát tệp dưới dạng application/linkset+json. Cấu hình nginx đặt media type này và thêm header Link với rel="api-catalog", theo yêu cầu của RFC 9727 đối với các yêu cầu HEAD.

## Vì sao nên xuất bản danh mục API

Trước khi gọi API, agent cần tìm được API đó. RFC 9727, được công bố vào tháng 6 năm 2025, quy định một điểm bắt đầu cố định cho việc tìm kiếm: URL well-known /.well-known/api-catalog, cùng với quan hệ liên kết api-catalog mà bất kỳ trang nào cũng có thể dùng để trỏ đến URL này.

Danh mục là một linkset ở định dạng JSON. Mỗi mục lấy URL cơ sở của API làm điểm neo và liên kết đến mô tả dành cho máy đọc (service-desc, thường là tệp OpenAPI), tài liệu dành cho người đọc (service-doc) và trang trạng thái. Client chỉ cần đọc một tệp nhỏ thay vì thu thập dữ liệu từ tài liệu của bạn.

RFC quy định phản hồi phải dùng application/linkset+json và nên có profile https://www.rfc-editor.org/info/rfc9727. Hiện chưa có dữ liệu về những agent nào yêu cầu tệp này, nhưng đây chỉ là một tệp tĩnh cần xuất bản.

## Câu hỏi về api-catalog

### /.well-known/api-catalog là gì?

Đây là vị trí được RFC 9727 quy định để lưu danh sách API của một tổ chức ở định dạng máy có thể đọc. Tệp này là một JSON linkset, liên kết từng API với mô tả, tài liệu và trạng thái của API đó. Client có thể truy cập trực tiếp tại đây hoặc tìm thấy tệp thông qua quan hệ liên kết api-catalog.

### api-catalog cần Content-Type nào?

RFC 9727 quy định Content-Type phải là application/linkset+json và nên có tham số profile https://www.rfc-editor.org/info/rfc9727. Cấu hình nginx trên trang này đặt media type và header Link; hãy tự thêm tham số profile nếu cấu hình máy chủ của bạn cho phép.

### Tôi có cần tệp OpenAPI để xuất bản danh mục không?

Không. Trong trình tạo này, mỗi mục chỉ cần URL cơ sở của API; các liên kết đến mô tả, tài liệu và trạng thái đều không bắt buộc. Mô tả OpenAPI giúp client tìm hiểu các endpoint mà không cần đọc tài liệu dạng văn bản, vì vậy hãy thêm mô tả này nếu bạn có.

### api-catalog khác llms.txt như thế nào?

api-catalog là RFC của IETF, liệt kê API dưới dạng liên kết JSON cho phần mềm gọi API. llms.txt là một đề xuất về chỉ mục trang ở định dạng Markdown, hướng đến các mô hình ngôn ngữ đọc tài liệu. Hai định dạng này không trùng lặp, nên bạn có thể xuất bản cả hai.

## Nguồn

1. [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9727)/rfc/rfc9727
2. [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9264)/rfc/rfc9264
3. [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc8631)/rfc/rfc8631

Tài liệu tham khảo độc lập dành cho những người xây dựng AI agent. Không liên kết với bất kỳ nhà cung cấp nào được nêu ở đây.

© 2026 DotsAgent · Dữ liệu được kiểm tra ngày 1 tháng 10, 2026