Generador de catálogo de API
Enumera tus API públicas una sola vez y obtén el conjunto de enlaces JSON que RFC 9727 requiere en /.well-known/api-catalog, junto con un bloque de nginx para servirlo con el tipo de medio correcto.
{
"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;
}
Sube el archivo a /.well-known/api-catalog y sírvelo como application/linkset+json. El bloque de nginx establece ese tipo y añade una cabecera Link con rel="api-catalog", como requiere RFC 9727 en las solicitudes HEAD.
Por qué publicar un catálogo de API
Antes de llamar a tu API, un agente tiene que encontrarla. RFC 9727, publicado en junio de 2025, define un punto de partida fijo para esa búsqueda: la URL conocida /.well-known/api-catalog y la relación de enlace api-catalog, que cualquier página puede usar para enlazarla.
El catálogo es un conjunto de enlaces en JSON. Cada entrada tiene como ancla la URL base de una API y enlaza con su descripción legible por máquinas (service-desc, normalmente un archivo OpenAPI), su documentación para personas (service-doc) y su página de estado. Así, un cliente lee un archivo pequeño en vez de rastrear tu documentación.
RFC 9727 indica que la respuesta debe usar application/linkset+json y debería incluir el perfil https://www.rfc-editor.org/info/rfc9727. Todavía no tenemos datos sobre qué agentes solicitan el archivo, pero solo hay que publicar un archivo estático.
Preguntas sobre api-catalog
¿Qué es /.well-known/api-catalog?
Es la ubicación que RFC 9727 define para una lista legible por máquinas de las API de una organización. El archivo es un conjunto de enlaces JSON que enlaza cada API con su descripción, documentación y estado. Los clientes pueden encontrarlo directamente ahí o mediante la relación de enlace api-catalog.
¿Qué Content-Type necesita api-catalog?
RFC 9727 indica que debe ser application/linkset+json y debería incluir el parámetro de perfil https://www.rfc-editor.org/info/rfc9727. El bloque de nginx de esta página establece el tipo de medio y la cabecera Link; añade el parámetro de perfil manualmente si la configuración de tu servidor lo permite.
¿Necesito un archivo OpenAPI para publicar un catálogo?
No. En este generador, cada entrada solo necesita la URL base de la API; los enlaces a la descripción, la documentación y el estado son opcionales. Una descripción OpenAPI permite que un cliente descubra tus endpoints sin leer texto explicativo, así que añádela si tienes una.
¿En qué se diferencia api-catalog de llms.txt?
api-catalog es un RFC de IETF que enumera API mediante enlaces JSON para el software que las consume. llms.txt es una propuesta para crear un índice de páginas en Markdown, dirigido a modelos de lenguaje que leen documentación. No se solapan, así que puedes publicar ambos.