Generatore di cataloghi API
Elenca una volta le tue API pubbliche e ottieni il linkset JSON previsto da RFC 9727 in /.well-known/api-catalog, insieme a un blocco nginx che lo serve con il media type corretto.
{
"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;
}
Carica il file in /.well-known/api-catalog e servilo come application/linkset+json. Il blocco nginx imposta questo media type e aggiunge un header Link con rel="api-catalog", previsto da RFC 9727 per le richieste HEAD.
Perché pubblicare un catalogo API
Prima di poterla chiamare, un agent deve trovare la tua API. RFC 9727, pubblicata a giugno 2025, definisce un punto di partenza univoco: l'URL well-known /.well-known/api-catalog e la relazione di link api-catalog, che qualsiasi pagina può usare per rimandare al catalogo.
Il catalogo è un linkset in formato JSON. Ogni voce ha come anchor l'URL di base di un'API e rimanda alla relativa descrizione leggibile dalle macchine (service-desc, di solito un file OpenAPI), alla documentazione per le persone (service-doc) e alla pagina di stato. Un client legge un solo file di piccole dimensioni, senza dover esplorare la documentazione.
RFC 9727 specifica che la risposta deve usare application/linkset+json e dovrebbe includere il profilo https://www.rfc-editor.org/info/rfc9727. Non abbiamo ancora dati sugli agent che richiedono il file, ma basta pubblicare un singolo file statico.
Domande su api-catalog
Che cos'è /.well-known/api-catalog?
È il percorso definito da RFC 9727 per un elenco leggibile dalle macchine delle API di un'organizzazione. Il file è un linkset JSON che rimanda da ogni API alla relativa descrizione, documentazione e pagina di stato. I client possono trovarlo direttamente in quel percorso o tramite la relazione di link api-catalog.
Quale Content-Type richiede api-catalog?
RFC 9727 specifica che deve essere application/linkset+json e dovrebbe includere il parametro profile https://www.rfc-editor.org/info/rfc9727. Il blocco nginx in questa pagina imposta il media type e l'header Link; aggiungi tu il parametro profile, se la configurazione del server lo consente.
Serve un file OpenAPI per pubblicare un catalogo?
No. In questo generatore, ogni voce richiede solo l'URL di base dell'API; i link alla descrizione, alla documentazione e allo stato sono facoltativi. Una descrizione OpenAPI permette a un client di scoprire i tuoi endpoint senza leggere testi esplicativi, quindi aggiungila se ne hai una.
In cosa api-catalog è diverso da llms.txt?
api-catalog è una RFC IETF che elenca le API sotto forma di link JSON, per i software che le chiamano. llms.txt è una proposta per un indice Markdown delle pagine, pensato per i modelli linguistici che leggono la documentazione. Non si sovrappongono, quindi puoi pubblicarli entrambi.