---
title: "Generatore di cataloghi API per /.well-known/api-catalog · DotsAgent"
description: "Crea il linkset JSON previsto da RFC 9727 per /.well-known/api-catalog, con ogni API, la relativa descrizione OpenAPI, la documentazione e la pagina di stato, oltre a un blocco nginx."
url: https://dotsagent.io/it/agent-ready/api-catalog
---

RFC 9727

# 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.

`/.well-known/api-catalog`

```
{
  "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"
        }
      ]
    }
  ]
}
```

`nginx`

```
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.

## Fonti

1. [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9727)/rfc/rfc9727
2. [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9264)/rfc/rfc9264
3. [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc8631)/rfc/rfc8631

Riferimento indipendente per chi sviluppa agenti IA. Non siamo affiliati a nessun fornitore citato qui.

© 2026 DotsAgent · Dati verificati il 1 ottobre 2026