Compatibilità e versionamento

L’API DUST è versionata nel percorso: ogni endpoint si trova sotto /api/v1. All’interno di una versione, facciamo evolvere continuamente l’API, ma secondo regole rigorose: le modifiche sono incrementali per impostazione predefinita, qualsiasi cambiamento che comprometterebbe un’integrazione correttamente realizzata passa prima attraverso un periodo di deprecazione e la specifica OpenAPI pubblicata costituisce in ogni momento la fonte autorevole del contratto.

Questa pagina definisce cosa si intende per integrazione “correttamente realizzata” e cosa promettiamo in cambio.

Cosa può cambiare senza preavviso

Le seguenti modifiche sono considerate retrocompatibili. Possono comparire in qualsiasi versione e la tua integrazione deve essere in grado di gestirle:

• Nuovi endpoint e nuove operazioni sui percorsi esistenti.
• Nuovi parametri di richiesta, header e campi del corpo facoltativi. Le richieste esistenti continuano a funzionare senza modifiche.
• Nuovi campi nelle risposte. Gli oggetti si ampliano nel tempo.
• Nuovi valori nei campi enumerati: con l’evoluzione del prodotto vengono aggiunti nuovi tipi di evento, stati e categorie.
• Nuovi codici di errore per modalità di errore che in precedenza venivano indicate con un codice generico.
• Documentazione, testo del campo message degli errori e ordine dei campi. Le stringhe leggibili dalle persone non fanno parte del contratto; l’ordine dei membri JSON non è mai significativo.

Scrivere un’integrazione che rimanga compatibile

Le regole precedenti sono sicure se il tuo client segue le prassi standard di lettura tollerante:

• Ignora i campi della risposta che non riconosci. Non generare mai un errore in presenza di membri imprevisti e non utilizzare una convalida rigorosa dello schema che rifiuti i campi sconosciuti.
• Gestisci i valori enum sconosciuti. Ramifica la logica in base ai valori che gestisci e prosegui correttamente con quelli che non riconosci.
• Ramifica la logica in base al campo code dell’errore, mai in base a message. I codici sono identificatori stabili; i messaggi sono localizzati e possono essere riformulati. Consulta Convenzioni per le richieste.
• Tratta gli ID e i cursori di paginazione come stringhe opache. Salvali e riutilizzali; non analizzarli né costruirli mai.
• Utilizza esclusivamente ciò che è documentato nella specifica pubblicata. Gli endpoint, i campi e i comportamenti non inclusi nella specifica OpenAPI pubblica non sono coperti da alcuna garanzia di compatibilità.

Un’integrazione che segue queste regole non risente delle modifiche incrementali ed è ciò che le promesse riportate di seguito intendono tutelare.

Cosa consideriamo una modifica incompatibile

Non apportiamo nessuna delle seguenti modifiche a un’operazione /api/v1 pubblicata senza seguire il processo di deprecazione descritto di seguito:

• Rimozione o ridenominazione di un endpoint, di un parametro di richiesta o di un campo della risposta.
• Modifica del tipo o del formato di un campo.
• Trasformazione di un input di richiesta facoltativo in obbligatorio oppure restrizione dei valori accettati da un input.
• Rimozione di un valore da un campo enumerato.
• Modifica del campo code dell’errore o dello stato HTTP restituito per una modalità di errore esistente e documentata.
• Richiesta di un livello di autorizzazione superiore o di una nuova autorizzazione per un’operazione esistente.
• Modifica sostanziale della semantica di un’operazione, anche se la sua struttura rimane invariata.

Deprecazione

Quando è necessario ritirare o ristrutturare qualcosa, tale elemento viene prima deprecato:

• L’operazione o il campo viene contrassegnato con deprecated: true nella specifica OpenAPI pubblicata e la deprecazione viene indicata in questa documentazione.
• La funzionalità deprecata continua a funzionare, senza modifiche, per almeno 90 giorni dall’annuncio.
• Quando esiste una funzionalità sostitutiva, questa viene documentata e resa disponibile prima della deprecazione o contestualmente a essa.

Controlla la specifica, non le comunicazioni sul canale

La specifica OpenAPI pubblicata all’indirizzo /openapi.json riflette sempre il contratto corrente, inclusi i marcatori di deprecazione. Confrontarla tra una revisione e l’altra della tua integrazione è il modo più affidabile per individuare le modifiche.

Versionamento

Le nuove versioni principali sono rare per scelta progettuale. /api/v1 evolve in modo incrementale; introdurremmo una /api/v2 soltanto per una ristrutturazione che non possa essere realizzata mantenendo la compatibilità. In tal caso, /api/v1 continuerebbe a essere supportata per un lungo periodo di migrazione, annunciato esplicitamente, e non verrebbe mai rimossa alla scadenza del periodo di deprecazione indicato sopra.

Vedi anche

• Convenzioni per le richieste — il contratto condiviso per le richieste a cui si applicano queste promesse.
• Autenticazione e chiavi API — account di servizio e durata dei token.
• Riferimento API completo — generato dalla specifica pubblicata.