Controllo versione semantico degli apis REST?

Question

Ho valutato un numero di schemi di versioning per apis REST (intestazione, url, ...). Finora, l'approccio più affidabile sembra essere l'opzione url: funziona con i proxy e non si basa su schemi oscuri come dates for versioning.

Ora, quando mi guardo intorno, tutti quelli che utilizzano l'approccio basato su URL sembrano utilizzare versioni come v1, v2 e così via. Nessuno usa versioni minori o anche uno schema come semantic versioning.

Ciò solleva alcune domande:

• Quando si fa a aumentare il numero di versione di un API REST (di sicuro, di avere ulteriori aggiornamenti ad esso non solo una volta ogni cinque anni)?
• Se si dispone solo di una correzione di bug, probabilmente non si aumenta il numero di versione, ma come si differenziano entrambe le versioni?
• Se si utilizza un approccio molto granulare, si finisce con lotti di versioni che è necessario ospitare in parallelo. Come lo gestisci?

In altre parole: Come fa una società come GitHub, per esempio, far avere solo v3 oggi (2015), quando sono in giro in attività già da 7 anni? Significa che in realtà hanno cambiato solo la loro api due volte? Non riesco a crederci.

Eventuali suggerimenti?

Answer 1

Il numero di versione principale è tutto ciò che serve per un servizio Web. Perché i tuoi consumatori sono preoccupati solo delle modifiche incompatibili con le versioni precedenti e (se stai seguendo correttamente il versioning semantico), questi verranno introdotti solo quando verrà rilasciata una nuova versione principale.

Tutte le altre modifiche (incluse nuove funzionalità, correzioni di errori, patch, ecc.) Devono essere "sicure" per i consumatori. Queste nuove funzionalità non hanno per essere utilizzate dai consumatori e probabilmente non si desidera continuare a eseguire quella versione senza patch che contiene bug X o Y più a lungo del necessario.

L'utilizzo del numero di versione completo negli URL (o qualsiasi altro metodo utilizzato per il controllo delle versioni dell'API) significherebbe effettivamente che i consumatori devono aggiornare l'URL dell'API ogni volta che si esegue un aggiornamento/bugfix alla propria API e continua a utilizzare una versione senza patch finché non lo fa.

Ciò non significa che non è possibile utilizzare la versione semantica delle versioni interne, ovviamente! Basta usare la prima parte (versione principale) come numero di versione per la tua API. Non ha senso includere il numero di versione completo nel tuo URL/header/altro sistema di controllo delle versioni.

Quindi, per rispondere alla tua domanda: aggiorni la tua API ogni volta che crei una nuova versione, ma rilasci una nuova versione dell'API quando hai una nuova versione principale. In questo modo devi solo ospitare un paio di versioni differenti (e puoi naturalmente deprecare le vecchie versioni nel tempo).