> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/it/docs/versioning

# Versionamento e deprecazioni

La versione dell'API fa parte del percorso, ad esempio /v1/status . All'interno di una versione, le richieste esistenti continuano a funzionare.

La versione dell'API fa parte del percorso, ad esempio `/v1/status`. All'interno di una versione, le richieste esistenti continuano a funzionare. Questa pagina spiega cosa può cambiare, con quanto preavviso e come individuare le richieste da aggiornare.

### Modifiche senza preavviso

Nuovi endpoint, parametri facoltativi, campi di risposta, valori in elenchi di opzioni esistenti, header di risposta e codici di errore possono essere aggiunti in qualsiasi momento. Scrivi client che ignorino i campi che non conoscono e gestiscano con correttezza i nuovi valori.

### Modifiche incompatibili

La rimozione o la ridenominazione di un endpoint, parametro o campo, o la modifica del suo significato, avviene solo dopo almeno 12 mesi di preavviso. In questo periodo la vecchia forma continua a funzionare, le risposte alle richieste che la usano riportano gli header `Deprecation` e `Sunset`, e la modifica è indicata nel changelog.

### Nomenclatura delle chiavi di risposta

La maggior parte delle chiavi di risposta è in snake_case. Per ricevere ogni chiave in snake_case, aggiungi `naming=snake` oppure invia l'header `DomScan-Naming: snake`. L'attivazione è facoltativa, quindi le risposte predefinite non cambiano. Vedi [chiavi snake_case](https://domscan.net/it/docs/response-format#naming).

### Alias deprecati

Questi parametri più vecchi funzionano ancora. Ciascuno continua a funzionare almeno fino alla propria data di dismissione. Passa al sostituto prima di tale data.

| Parametro | Endpoint | Usa invece | Deprecato dal | Dismissione |
| --- | --- | --- | --- | --- |
| `prefer_cache` | `GET /v1/status` | `max_age=2592000` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/status` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `cache_skip` | `GET /v1/status` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `cache-skip` | `GET /v1/status` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `options.prefer_cache` (Body JSON) | `POST /v1/status/bulk` | `max_age=2592000` | 2026-10-10 | 2027-10-10 |
| `prefer_cache` (Body JSON) | `POST /v1/status/bulk` | `max_age=2592000` | 2026-10-10 | 2027-10-10 |
| `options.skip_cache` (Body JSON) | `POST /v1/status/bulk` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `options.cache_skip` (Body JSON) | `POST /v1/status/bulk` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `options.cache-skip` (Body JSON) | `POST /v1/status/bulk` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `prefer_cache` | `GET /v1/subdomains` | `max_age=2592000` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/tech` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/categorize` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/identity-assets` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/identity-resolution` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/url-intelligence` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/agent-readiness` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `skip_cache` | `GET /v1/robots` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `refresh` | `GET /v1/ssl/deep-scan` | `max_age=0` | 2026-10-10 | 2027-10-10 |
| `cursor` (valore numerico) | `GET /v1/certificates` | `cursor=<next_cursor>` | 2026-10-10 | 2027-10-10 |
| `offset` | `GET /v1/email/blacklist` | `cursor=<next_cursor>` | 2026-10-10 | 2027-10-10 |

### Individuare le deprecazioni

Una richiesta che usa un alias deprecato riceve questi header di risposta. Il corpo della risposta resta invariato.

- `Deprecation`: la data in cui l'alias è stato deprecato, come `@` seguito da secondi Unix (RFC 9745).

- `Sunset`: la data più vicina in cui l'alias potrebbe smettere di funzionare (RFC 8594).

- `Link`: un link a questa pagina con `rel="deprecation"`.

```bash
curl -i -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/status?name=example&tlds=com&skip_cache=true"

Deprecation: @1791590400
Sunset: Sun, 10 Oct 2027 00:00:00 GMT
Link: <https://domscan.net/docs/versioning#deprecated-aliases>; rel="deprecation"; type="text/html"
```

I browser possono leggere tutti e tre gli header. Registrali nei log o imposta un avviso su `Deprecation` per trovare il codice da aggiornare prima della data di dismissione.

Ogni deprecazione viene annunciata anche nel [changelog dell'API](https://domscan.net/it/changelog).