Versioni e compatibilità

L’API ha una sola versione principale, /v1, che si limita a crescere. Un’integrazione scritta oggi continua a funzionare man mano che arrivano nuove funzionalità: nulla di ciò su cui si basa viene rinominato, rimosso o cambia significato.

Il numero di versione

L’API ha un numero di versione come 1.62.0. Cambia a ogni rilascio:

• il numero della versione minore quando si aggiunge qualcosa: un endpoint, un campo, un evento;
• il numero della patch quando si corregge una descrizione o il testo di un messaggio e non cambia nient’altro.

Puoi leggere in qualsiasi momento la versione servita da un indirizzo:

Anche GET /v1/health ha un campo version, ma è la versione della release di Sursa che serve l’indirizzo, non la versione dell’API.

Non scegli una versione minore: ogni richiesta è servita da quella attuale. Grazie alle regole seguenti, è sicuro.

Cosa può cambiare in /v1

Queste modifiche possono arrivare in qualsiasi versione minore. Scrivi la tua integrazione in modo che non la rompano:

• Nuovi endpoint.
• Nuovi parametri e campi della richiesta facoltativi. Le richieste senza di essi si comportano come prima.
• Nuovi campi in risposte, oggetti ed eventi.
• Nuovi valori di enumerazioni nelle risposte, come un nuovo stato di una scheda o un nuovo tipo di evento.
• Nuovi codici di errore e nuove intestazioni di risposta.
• Limiti che diventano meno severi: una lunghezza massima maggiore, un intervallo più ampio.
• Testi message degli errori e descrizioni riformulati.

Cosa deve tollerare il tuo codice

• Ignora i campi che non conosci. Non andare in errore quando una risposta ha più campi di quelli che ti aspetti, e non usare schemi rigidi che li rifiutano.
• Accetta i valori di enumerazione che non conosci. Ogni enumerazione in una risposta può crescere. Tratta un valore sconosciuto come “altro” anziché come un errore.
• Ignora i tipi di evento che non conosci, sia nei webhook sia negli stream.
• Gestisci i codici di errore sconosciuti in base al loro stato HTTP: vedi Errori.
• Non dipendere dall’ordine dei campi negli oggetti JSON, né dal testo esatto dei messaggi.

Cosa non cambia mai in /v1

• Un percorso, un parametro, un campo o un valore di enumerazione non viene mai rinominato né rimosso.
• Il tipo di un campo non cambia mai, e un campo non assume mai un nuovo significato, come nuove unità di misura.
• Una richiesta accettata oggi non viene rifiutata in futuro.
• Il codice di stato di una risposta riuscita resta lo stesso.
• I codici di errore mantengono il loro significato e il campo detail delle risposte di errore mantiene la sua forma.
• I tipi di evento non vengono mai rinominati né rimossi, e il loro data acquisisce solo nuovi campi.

Modifiche incompatibili

Se mai servisse una modifica incompatibile, verrebbe rilasciata come nuova versione principale, come /v2, accanto a /v1. /v1 continua a funzionare senza modifiche e le due versioni convivono.

Quando una route sta per essere ritirata:

1. Viene contrassegnata come deprecated nella specifica ed elencata nel registro delle modifiche con la data in cui verrà disattivata.
2. Le sue risposte portano le intestazioni Deprecation: true e Sunset: <date>.
3. Continua a funzionare per almeno 180 giorni dopo l’annuncio. Le organizzazioni le cui chiavi API la usano vengono avvisate per iscritto con almeno 90 giorni di anticipo.
4. Dopo la data di dismissione, risponde 410 con il codice api.gone per altri 90 giorni.

Tieni d’occhio l’intestazione Deprecation nei tuoi log o nel monitoraggio: è il primo segnale che una route che usi sta per scomparire.

Restare aggiornati

Il registro delle modifiche di questo portale elenca ogni rilascio con ciò che è stato aggiunto e ciò che è stato deprecato. Prima di aggiornare la tua integrazione, confronta il suo codice con le voci successive alla versione per cui l’hai scritta.