Generator katalog API
Cantumkan API publik Anda sekali saja dan dapatkan JSON linkset yang diwajibkan RFC 9727 di /.well-known/api-catalog, beserta konfigurasi nginx untuk menyajikannya dengan tipe media yang tepat.
{
"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"
}
]
}
]
}
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;
}
Unggah file ke /.well-known/api-catalog dan sajikan sebagai application/linkset+json. Konfigurasi nginx menetapkan tipe tersebut dan menambahkan header Link dengan rel="api-catalog", sebagaimana diwajibkan RFC 9727 untuk permintaan HEAD.
Mengapa menerbitkan katalog API
Sebelum memanggil API Anda, agen harus menemukannya terlebih dahulu. RFC 9727, yang diterbitkan pada Juni 2025, menetapkan titik awal yang baku untuk pencarian tersebut: URL well-known /.well-known/api-catalog, serta relasi tautan api-catalog yang dapat digunakan halaman mana pun untuk mengarah ke sana.
Katalog ini berupa linkset dalam format JSON. Setiap entri menggunakan URL dasar API sebagai anchor, lalu menautkan ke deskripsi yang dapat dibaca mesin (service-desc, biasanya file OpenAPI), dokumentasi untuk manusia (service-doc), dan halaman statusnya. Klien cukup membaca satu file kecil, alih-alih merayapi dokumentasi Anda.
RFC menyatakan bahwa respons harus menggunakan application/linkset+json dan sebaiknya menyertakan profil https://www.rfc-editor.org/info/rfc9727. Kami belum memiliki data tentang agen mana yang meminta file ini, tetapi Anda hanya perlu menerbitkan satu file statis.
Pertanyaan tentang api-catalog
Apa itu /.well-known/api-catalog?
RFC 9727 menetapkan lokasi ini untuk daftar API organisasi yang dapat dibaca mesin. File tersebut berupa JSON linkset yang menautkan setiap API ke deskripsi, dokumentasi, dan halaman statusnya. Klien dapat menemukannya langsung di lokasi tersebut atau melalui relasi tautan api-catalog.
Content-Type apa yang diperlukan api-catalog?
RFC 9727 menyatakan bahwa Content-Type harus berupa application/linkset+json dan sebaiknya menyertakan parameter profil https://www.rfc-editor.org/info/rfc9727. Konfigurasi nginx di halaman ini menetapkan tipe media dan header Link. Tambahkan sendiri parameter profil jika konfigurasi server Anda mendukungnya.
Apakah saya perlu file OpenAPI untuk menerbitkan katalog?
Tidak. Dalam generator ini, setiap entri hanya memerlukan URL dasar API. Tautan deskripsi, dokumentasi, dan status bersifat opsional. Deskripsi OpenAPI memungkinkan klien mempelajari endpoint Anda tanpa membaca uraian teks, jadi tambahkan jika tersedia.
Apa perbedaan api-catalog dan llms.txt?
api-catalog adalah RFC IETF yang mencantumkan API sebagai tautan JSON untuk perangkat lunak yang memanggilnya. llms.txt adalah proposal indeks halaman dalam format Markdown yang ditujukan untuk model bahasa yang membaca dokumentasi. Keduanya tidak tumpang tindih, jadi Anda dapat menerbitkan keduanya.