Questa è una variante del versioning semantico (che dovresti anche leggere):
- Stabilire un numero di versione per l'API, con numeri principali e secondari separati. Includilo esplicitamente nel file JSON e (se possibile) nell'handshake del protocollo. Inizia dalla versione 1.0 (major.minor).
- Quando modifichi un'API compatibile con le versioni precedenti, incrementa il numero secondario.
- Quando si modifica un'API incompatibile all'indietro, incrementa il numero maggiore e reimposta il numero minore su 0.
- Quando si stabilisce una connessione, se i numeri maggiori non corrispondono, si fallisce l'handshake o si ricorre a una versione precedente del codice, se disponibile.
- Non apportare modifiche non reversibili all'indietro (o affatto).
Non conosco i dettagli della tua API, ma qui ci sono alcuni esempi di modifiche compatibili con le versioni precedenti:
- Presentazione di un nuovo tipo di messaggio. *
- Aggiunta di un campo facoltativo a un messaggio esistente, con il comportamento predefinito (quando il campo non viene fornito) identico al comportamento precedente.
- Indebolimento di una precondizione.
- Rafforzamento di una post-prenotazione.
- Contrassegnare un tipo di messaggio come deprecato, senza rimuoverlo o alterarlo.
Ecco alcuni esempi di modifiche incompatibili:
- Rimozione di un tipo di messaggio.
- Rimozione di un campo da un tipo di messaggio.
- Aggiunta di un campo obbligatorio a un tipo di messaggio.
- Modifica del comportamento di un messaggio in un modo che l'altro lato dell'API potrebbe ragionevolmente notare (ad esempio, l'introduzione di un livello di memorizzazione nella cache va bene, restituire risultati diversi non lo è).
- Rafforzamento di una precondizione.
- Indebolimento di una post-condizione.
Tecnicamente, non hai proprio bisogno del numero minore. Potresti semplicemente affidarti al controllo della versione per tenere traccia di queste informazioni. Ma i numeri di versione sono più intuitivi degli hash di commit e potresti voler eseguire il rilevamento delle funzioni con il numero minore.
Se non si interrompe la compatibilità con le versioni precedenti, non è necessario nemmeno il numero maggiore. Ma è una buona idea averlo nel caso in cui sia necessario fare un cambio di rottura. Tali cambiamenti dovrebbero essere rari.
D'altra parte, se la tua API non è ancora stata pubblicata e non hai alcun codice cliente che potrebbe essere influenzato dall'incompatibilità con le versioni precedenti, puoi iniziare il numero maggiore a zero invece di uno, per indicare che l'API è provvisorio. Quindi puoi semplicemente apportare le modifiche incompatibili all'indietro che ti piacciono senza toccare il numero maggiore e quando sei pronto per "passare all'oro", vai alla versione 1.0.
* Se è possibile che il destinatario del messaggio sia più vecchio del mittente, è necessario assicurarsi che sia il mittente sia il destinatario siano in grado di gestire il caso in cui il destinatario non riconosce un messaggio o un particolare campo del messaggio . Nelle tipiche API Web server-client, questo è raramente un problema, ma per le API dell'hardware la situazione potrebbe essere molto diversa. È possibile che tu debba considerare questo come un cambio di rottura, il che rende molto più difficile seguire alcuni di questi consigli.