API kataloğu oluşturucu
Herkese açık API'lerinizi bir kez listeleyin; RFC 9727'nin /.well-known/api-catalog adresinde beklediği JSON linkset'i ve dosyayı doğru medya türüyle sunan bir nginx bloğunu alın.
{
"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;
}
Dosyayı /.well-known/api-catalog adresine yükleyin ve application/linkset+json olarak sunun. nginx bloğu bu medya türünü ayarlar ve rel="api-catalog" içeren bir Link başlığı ekler; RFC 9727, HEAD isteklerinde bunu bekler.
Neden API kataloğu yayımlamalısınız?
API'nizi çağırmak isteyen bir ajan önce onu bulmalıdır. Haziran 2025'te yayımlanan RFC 9727, arama için sabit bir başlangıç noktası tanımlar: /.well-known/api-catalog iyi bilinen URL'si ve herhangi bir sayfanın bu URL'ye işaret etmek için kullanabileceği api-catalog bağlantı ilişkisi.
Katalog, JSON biçiminde bir linkset'tir. Her girdi, bir API'nin temel URL'sini sabitleyerek makine tarafından okunabilir açıklamasına (service-desc; genellikle bir OpenAPI dosyası), insanlara yönelik dokümantasyonuna (service-doc) ve durum sayfasına bağlantı verir. İstemci, dokümantasyonunuzu taramak yerine küçük bir dosyayı okur.
RFC, yanıtın application/linkset+json kullanmasını zorunlu kılar ve https://www.rfc-editor.org/info/rfc9727 profilini taşımasını önerir. Dosyayı hangi ajanların istediğine dair henüz verimiz yok, ancak yayımlamak için tek bir statik dosya yeterlidir.
api-catalog hakkında sorular
/.well-known/api-catalog nedir?
RFC 9727'nin bir kuruluşun API'lerini makine tarafından okunabilir biçimde listelemek için tanımladığı konumdur. Dosya, her API'den açıklamasına, dokümantasyonuna ve durum sayfasına bağlantı veren bir JSON linkset'tir. İstemciler bu dosyayı doğrudan burada veya api-catalog bağlantı ilişkisi üzerinden bulabilir.
api-catalog için hangi Content-Type gerekir?
RFC 9727, application/linkset+json kullanılmasını zorunlu kılar ve https://www.rfc-editor.org/info/rfc9727 profil parametresinin eklenmesini önerir. Bu sayfadaki nginx bloğu medya türünü ve Link başlığını ayarlar; sunucu yapılandırmanız izin veriyorsa profil parametresini kendiniz ekleyin.
Katalog yayımlamak için OpenAPI dosyasına ihtiyacım var mı?
Hayır. Bu oluşturucuda her girdi için yalnızca API'nin temel URL'si gerekir; açıklama, dokümantasyon ve durum bağlantıları isteğe bağlıdır. OpenAPI açıklaması, istemcinin metinleri okumadan endpoint'lerinizi öğrenmesini sağlar; varsa ekleyin.
api-catalog ile llms.txt arasındaki fark nedir?
api-catalog, API'leri onları çağıran yazılımlar için JSON bağlantıları olarak listeleyen bir IETF RFC'sidir. llms.txt ise dokümantasyonu okuyan dil modellerini hedefleyen, sayfalar için Markdown dizini önerisidir. Birbirleriyle örtüşmezler; ikisini de yayımlayabilirsiniz.