Compatibilità
Compatibilità
Che cosa possiamo cambiare in v1 senza preavviso e che cosa richiederebbe una nuova versione maggiore. È enunciato come elenco e non come promessa, perché un'integrazione possa difendersi esattamente dall'insieme giusto.
Percorsi, metodi, ambiti, nomi dei campi e codici di errore sono pubblicati in inglese, perché l'inglese è la lingua dell'interfaccia stessa: è ciò che un chiamante digita o confronta. Lo stesso vale per ogni esempio di codice, ogni payload JSON e la frase esatta che una risposta di errore porta con sé: /v1 non legge Accept-Language, e tradurre ciò che l'API invia davvero la descriverebbe in modo scorretto. Tutto ciò che viene scritto al riguardo segue la lingua di questa pagina.
La revisione corrente è 2026-08-01. Il percorso resta /v1; la revisione identifica il documento che lo descrive.
Modifiche che non faremo a v1
Queste richiedono una nuova versione maggiore. Se mai ne servisse una, le versioni esistenti continuerebbero a rispondere durante la migrazione.
- Rimuovere un'operazione.
- Rimuovere o rinominare un parametro, oppure un campo di una risposta.
- Aggiungere un nuovo parametro obbligatorio.
- Rendere obbligatorio un parametro finora facoltativo.
- Cambiare il tipo di un parametro o di un campo di risposta.
- Rimuovere un valore da un enum.Un client che ramifica su quel valore non ha un ramo per la sua assenza, quindi fallisce nel modo in cui il suo linguaggio fallisce davanti a un caso non gestito.
- Aggiungere una nuova regola di validazione a un parametro esistente.Una richiesta che ieri andava a buon fine comincerebbe a fallire: è una funzionalità tolta, travestita da correzione di un difetto.
- Cambiare i requisiti di autenticazione o di autorizzazione, compreso l'ambito che un'operazione richiede.
Modifiche che possiamo fare in qualsiasi momento
La sua integrazione deve tollerarle tutte. Accadranno, e non saranno annunciate.
- Aggiungere una nuova operazione.
- Aggiungere un nuovo parametro facoltativo.
- Aggiungere una nuova intestazione di richiesta facoltativa.
- Aggiungere un nuovo campo a una risposta.Analizzi le risposte in modo permissivo: un client che rifiuta i campi sconosciuti si romperà alla nostra prima aggiunta.
- Aggiungere una nuova intestazione di risposta.
- Aggiungere un valore a un enum.Gestisca un valore non riconosciuto come caso predefinito e non come errore. Compariranno nuove categorie di passaporto e nuovi tipi di evento.
- Suddividere un codice di errore in codici più precisi — ma solo dove l'originale non poteva essere risolto dalla logica in esecuzione, per esempio con un nuovo tentativo.Suddividere un codice su cui un client RAMIFICA rompe la compatibilità; suddividerne uno che si limita a registrare a log no. La distinzione sta nel fatto che il comportamento ne dipendesse o meno.
Che cosa il suo client deve tollerare
Ciascuno di questi punti corrisponde a una modifica qui sopra che ci riserviamo di fare. Un client che ne violi uno si romperà su qualcosa che noi consideriamo ordinario.
- Ignori i campi di risposta che non riconosce, invece di rifiutare la risposta.
- Tratti un valore di enum non riconosciuto come caso predefinito, non come errore.
- Tratti gli identificativi come stringhe opache; non li analizzi mai e non ne verifichi il formato.
- Non faccia affidamento sull'ORDINE dei campi in un oggetto JSON, né sulla formulazione esatta di un messaggio di errore leggibile da una persona. Ramifichi invece sul codice di errore leggibile dalle macchine.
- Riprovi su 429 e su qualunque altro rifiuto che porti un’intestazione Retry-After, attendendo il tempo che indica. Non è un’intestazione riservata al 429: la portano anche un 409 resource_busy, un 503 storage_unavailable e un 503 entitlement_unavailable, perché lì riprovare è il rimedio.
- Riprovi un 5xx con una NUOVA Idempotency-Key. Una chiave che ha registrato un errore del server riproduce quello stesso errore per tutta la finestra di conservazione — deliberatamente, perché il fallimento potrebbe essere stato la perdita della risposta a una scrittura RIUSCITA, e riusare la chiave è ciò che impedisce a una scrittura fallita di diventarne due.
- Tenga d'occhio le intestazioni di risposta Deprecation e Sunset, e il Link: rel="successor-version" che portano con sé. È così che viene annunciata la rimozione di un endpoint, e arriva molto prima che l'endpoint smetta di rispondere.
Tratti ogni identificativo come una stringa opaca di al massimo 255 caratteri. Non li analizzi, non ne convalidi il formato e non dia per scontato che siano UUID: il formato può cambiare senza preavviso.
Deprecazione
Un endpoint destinato alla rimozione risponde con le intestazioni Deprecation e Sunset e con un’intestazione Link che nomina il suo successore. Arrivano molto prima che l’endpoint smetta di rispondere. Le tenga d’occhio.