Interoperabilità tra versioni client e server

Proxy personalizzati e stub, che gestiscono l'adattamento della versione

Quindi, per fare in modo che funzioni bene, devi eseguire la versione dell'API. Ogni versione diversa dell'API che può vedere un'azione nel campo richiede una nuova versione.

Quindi creo una libreria (per qualsiasi lingua che accederà a questa API WS), che è il binding della lingua madre per tale API.

note - alcune lingue forniscono strumenti per creare automaticamente proxy e stub. Sebbene possano essere utilizzati internamente, non dovrebbero essere pubblicati direttamente per questo scopo (libreria client / stub per l'API del servizio).

L'API della libreria pubblicata deve sempre corrispondere alla versione ULTIMA del protocollo (il più fedelmente possibile, molto raramente potrebbe essere necessario generalizzare leggermente per adattarsi a versioni diverse).

Questa API proxy / stub, all'inizio della comunicazione, è in grado di stabilire la versione del peer con cui sta parlando e di eseguire il downgrade delle comunicazioni in base alle esigenze.

note - come tipicamente , per la maggior parte dei metodi, questo strato proxy / stub può essere piuttosto semplice, ma fornisce un livello in cui avviene la traduzione di tutti i protocolli.

Quindi, tutto il resto del codice server / client (di nuovo, in qualunque linguaggio di programmazione) - è appena scritto sull'API della libreria - che corrisponde alla versione più recente (al momento in cui il codice client / server è scritto) del protocollo.

Ho usato questo approccio su più progetti, con C ++, python, C # .net e javascript.

Concentrati sull'assicurare che i messaggi passati tra diverse versioni del protocollo possano essere compresi.

In generale, questo significa

• Non aggiungi mai un nuovo campo obbligatorio a un messaggio
• È possibile aggiungere campi facoltativi, ma nel protocollo
è necessario specificare un valore predefinito
• I campi non vengono mai riutilizzati per un nuovo significato.
• I consumatori devono ignorare i campi facoltativi non riconosciuti

Quindi se mi invii un messaggio con campi facoltativi di cui non conosco, lo ignoro. Se nel tuo messaggio manca un campo opzionale che mi aspetto, allora posso usare il protocollo dei messaggi per determinare quale valore predefinito dovrebbe essere usato.

Un riferimento che copre abbastanza bene questo è Versioning in un sistema di approvvigionamento di eventi di Greg Young.

Quando XML era in ascesa, la semantica Must ignorante era un argomento comune. Vedi David Orchard.

• 2004 Estensibilità, XML Vocabularies e XML Schema
• 2003 Versioning Vocabularies XML

Potresti anche dare un'occhiata a Eric Wilde: Modelli per la robusta estensibilità .

Version your server API . Il client non ha bisogno di sapere qual è la versione corrente dell'API, il client deve sapere quale versione dell'API supporta le tue istanze.

Ci sono due opzioni generali per richiedere una risorsa con versione. Puoi includere la versione richiesta dall'URI o includerla in un'intestazione HTTP:

Esempio di controllo delle versioni nell'URI:

GET http://instance{x}.myplatform.com/v1/{resource}

Esempio di controllo delle versioni nelle intestazioni:

GET http://instance{x}.myplatform.com/{resource}
X-API-Version: v1

GET http://instance{x}.myplatform.com/{resource}
Accept: application/json+v2

Naturalmente, potresti anche scegliere di supportare entrambi i metodi. Si noti che sto solo includendo il numero di versione principale. Se stai aderendo al versioning semantico , il cliente deve solo essere a conoscenza del numero di versione principale che sta utilizzando (poiché cambia solo quando interruzioni di compatibilità all'indietro). È possibile scegliere di fornire l'intero numero di versione se lo si desidera, ma potrebbe aumentare la logica che è necessario gestire sul lato server per determinare quale codice deve essere eseguito. Il client sa a quale versione dell'API è stato sviluppato, quindi dovrebbe essere in grado di rendere tali informazioni disponibili al momento della richiesta.

Questo significa che è necessario avere versioni precedenti della tua API in giro, ma ha senso dal momento che hai versioni precedenti del tuo client in circolazione senza controllo su quando vengono aggiornate. Puoi monitorare l'utilizzo della tua API in base alla versione e prendere la decisione di staccare la spina e rimuoverla completamente ogni volta che scende al di sotto di qualche soglia.

Il tuo approccio /version.json potrebbe essere utile se le tue istanze API possono mai trovarsi in uno stato in cui hanno versioni principali diverse che supportano. In tal caso, prima che l'utente selezioni l'istanza a cui desiderano connettersi, è necessario interrogarli e determinare se supportano la versione dell'API richiesta dal client. In caso contrario, il client non vorrebbe connettersi a loro.