Generator ng API catalog
Ilista nang isang beses ang mga pampublikong API mo at kunin ang JSON linkset na hinihingi ng RFC 9727 sa /.well-known/api-catalog, kasama ang nginx block na naghahatid nito gamit ang tamang media type.
{
"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;
}
I-upload ang file sa /.well-known/api-catalog at ihatid ito bilang application/linkset+json. Itinatakda ng nginx block ang type na iyon at nagdaragdag ng Link header na may rel="api-catalog", na hinihingi ng RFC 9727 para sa mga HEAD request.
Bakit mag-publish ng API catalog
Para matawag ng isang agent ang API mo, kailangan muna nitong mahanap iyon. Nagbibigay ang RFC 9727, na inilathala noong Hunyo 2025, ng nakapirming panimulang lugar para sa paghahanap na iyon: ang well-known URL na /.well-known/api-catalog, at ang relasyong api-catalog na maaaring gamitin ng anumang page para ituro roon.
JSON linkset ang catalog. Nakaangkla ang bawat entry sa base URL ng isang API at may mga link papunta sa machine-readable description nito (service-desc, karaniwang OpenAPI file), dokumentasyong para sa tao (service-doc) at status page nito. Isang maliit na file lang ang kailangang basahin ng client sa halip na i-crawl ang dokumentasyon mo.
Ayon sa RFC, dapat gamitin ng response ang application/linkset+json at dapat itong maglaman ng profile na https://www.rfc-editor.org/info/rfc9727. Wala pa kaming datos kung aling mga agent ang humihiling ng file, pero isa lang itong static file na kailangang i-publish.
Mga tanong tungkol sa api-catalog
Ano ang /.well-known/api-catalog?
Ito ang lokasyong itinatakda ng RFC 9727 para sa machine-readable na listahan ng mga API ng isang organisasyon. JSON linkset ang file na nag-uugnay sa bawat API sa description, dokumentasyon at status nito. Direktang mahahanap ito roon ng mga client o sa pamamagitan ng relasyong api-catalog.
Anong Content-Type ang kailangan ng api-catalog?
Ayon sa RFC 9727, dapat itong application/linkset+json at dapat maglaman ng parameter na profile na https://www.rfc-editor.org/info/rfc9727. Itinatakda ng nginx block sa page na ito ang media type at Link header; ikaw mismo ang magdagdag ng parameter na profile kung pinapayagan ito ng setup ng server mo.
Kailangan ko ba ng OpenAPI file para mag-publish ng catalog?
Hindi. Sa generator na ito, base URL lang ng API ang kailangan sa bawat entry. Opsyonal ang mga link para sa description, docs at status. Sa pamamagitan ng OpenAPI description, malalaman ng client ang mga endpoint mo nang hindi kailangang magbasa ng paliwanag, kaya idagdag ito kung mayroon ka na.
Ano ang kaibahan ng api-catalog sa llms.txt?
IETF RFC ang api-catalog na naglilista ng mga API bilang JSON link para sa software na tumatawag sa mga ito. Panukala naman ang llms.txt para sa Markdown index ng mga page, na para sa mga language model na nagbabasa ng dokumentasyon. Hindi nagsasapawan ang gamit ng mga ito, kaya maaari mong i-publish ang dalawa.