Skip to main content
La versione major è nel path: /v1. Dentro /v1 il contratto cambia solo in modo additivo:
  • nuovi endpoint;
  • nuovi parametri di query facoltativi;
  • nuovi campi nelle risposte;
  • nuovi codici di errore per situazioni nuove.
Costruisci il client in modo che queste novità non lo rompano: ignora i campi della risposta che non conosci e, per un codice di errore sconosciuto, affidati allo stato HTTP.

​
Modifiche incompatibili

Tutto il resto è una modifica incompatibile: rimuovere o rinominare un campo o un endpoint, cambiare il tipo o il significato di un campo, aggiungere un valore a un enum esistente come status, oppure rendere obbligatorio un parametro. Una modifica incompatibile ha un preavviso di almeno 6 mesi nel registro delle modifiche, con che cosa cambia, che cosa devi fare e la prima data in cui il comportamento precedente viene ritirato. Quando è possibile esce come nuova versione major (/v2), mentre /v1 continua a funzionare fino a quella data.

​
Dove vengono annunciate le modifiche

Ogni modifica pubblicata dell’API ha una voce datata nel registro delle modifiche. Produzione e staging cambiano insieme, e lo staging viene aggiornato per primo.