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.
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. 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.
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 conrel="deprecation".
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.