Strategie per l'aggiornamento o la versione dei servizi Web?

Question

Sono interessato a conoscere le migliori pratiche su come vengono gestite diverse versioni dei servizi web.

Per chiarire, se alcuni metodi Web sono esposti come un servizio Web, quindi si desidera aggiungere una funzionalità/funzionalità e quindi modificare la firma di tali chiamate di metodo, come gestirlo in un modo che non rompere tutti i tuoi clienti che attualmente chiamano il servizio?

Distribuisci il servizio su un URL diverso?

si fa a mettere una versione nel nome del metodo stesso (MyMethod, MyMethodv2 ecc - ugh ..)

fa a passare in una versione come parte della chiamata al metodo insieme a un elenco di parametri?

Qualcuno sa come Google o Amazon gestiscono questo scenario con la loro vasta libreria di servizi Web?

MODIFICA: Finora ho trovato delle buone informazioni in questo article from Oracle. Anche this blog entry su alcuni specifici di Java era utile. Sono ancora curioso di vedere alcuni degli altri approcci.

Answer 1

Il modo tipico di eseguire il controllo di versione di un servizio Web consiste nel richiedere ai client di specificare la versione desiderata. Puoi consentire vincoli semplici, come "> 2.0", "< 1.5" o "= 1.1". Ovviamente, vuoi minimizzare il numero di versioni supportate per la tua sanità mentale. Se un client non specifica una versione, si assume l'ultima.

Le tecniche per fornire la versione variano. Alcuni sostengono l'uso dell'URL, altri incoraggiano le intestazioni, alcuni potrebbero includerlo come parametro della chiamata API. Quasi nessuno cambierebbe il nome del metodo, comunque. È equivalente alla versione "pacchetto" o "spazio dei nomi" di cui parla il collegamento OSGi. Renderà l'aggiornamento molto difficile e impedirà alle persone di eseguire l'aggiornamento più di qualsiasi modifica al servizio effettivo.

Dipende anche da come accedi ai tuoi servizi web. Se stai utilizzando REST, mantenere le intestazioni pulite e utilizzabili dell'URL è più sensato (e sarebbe banale inserirla come parametro di query, se necessario). Se stai usando SOAP/XMLRPC/qualunque-RPC, metterlo nell'URL di solito va bene.

Modifica 5/2011 FWIW, anche se non sono d'accordo, Apigee's blog recommends putting the version in the URL.

Come il client specifica che la versione di solito è piuttosto semplice. Che cosa è più complicato è come si eseguono tutte le versioni contemporaneamente. La maggior parte delle lingue non ha un modo di caricare più versioni della stessa libreria/modulo/classe/funzione nello stesso ambiente di runtime (che si tratti di una VM, di un processo o di cosa hai). Il collegamento OSGi fornito è la soluzione Java per consentire ciò.

In pratica, OSGi sarà eccessivo per la maggior parte delle situazioni. Solitamente è più semplice eseguire il proxy delle richieste deprecate su un altro server o processo.

Il modo migliore per "eseguire" i propri servizi, tuttavia, è creare estendibilità e flessibilità in modo che rimangano compatibili con le versioni precedenti e successive. Ciò non significa che tutte le versioni devono essere compatibili tra loro, ma le versioni consecutive devono essere compatibili tra loro.

Answer 2

Posso dirti che la soluzione di creare doAPIFunction, doAPIFunctionV2 e doAPIFunctionV3, ecc. Non ha prodotto altro che mal di testa nel posto in cui lavoro. Aggiungete a ciò la mancanza di nomi di funzioni chiaramente descrittivi significa ogni genere di follia.

Si desidera cancellare i nomi delle funzioni API e, se una API sta cambiando, l'obiettivo è provare a farlo nel modo più compatibile con le versioni precedenti. Suggerirei il versioning dei punti di ingresso in modo che ogni punto di ingresso supporti un'API stabile e doFunction in example.org/api-1.0/ potrebbe essere diverso da example.org/api-2.0 se ci fossero buoni motivi per cambiare la semantica.

Answer 3

Non sono sicuro di aver capito correttamente la domanda. Ma i miei 2 centesimi. Se la firma del metodo cambia come un altro nuovo parametro, allora perché non può essere reso opzionale? Ma se un tipo di dati dei parametri esistente viene modificato, non è applicabile.

Vota questo giù se è sbagliato. :)

Answer 4

Era più semplice quando si potevano avere lo stesso nome del metodo di servizio web e diversi parametri, anni fa. :)

Una volta che si scrive un servizio web, si sta facendo un contratto con i clienti che questo è ciò che sosterrete.

Per i metodi precedenti suggerirei di loggare per vedere se sono stati utilizzati e da chi, per vedere se è possibile farli aggiornare.

Diversamente da ciò che è meglio fare è semplicemente scrivere un nuovo metodo, quindi potresti avere diversi nomi di funzioni simili che differiscono per una versione.

Il problema con il passaggio di un numero di versione è che è necessario assicurarsi che i client passino sempre un numero valido, il che, se si generano gli stub funzionerà, ma se non lo si fa, allora questo è molto fragile.

Inserire un numero di versione nel nome sembra funzionare al meglio per me, in quanto rende ovvio ciò che è vecchio, ed è possibile utilizzare AOP per registrare più facilmente versioni precedenti dei metodi di servizio web.

Answer 5

Un modo per mitigare questo è quello di codice per contratto e impostazione di interfacce in pietra. Non è mai possibile realmente modificare le firme delle funzioni, tuttavia è possibile sovraccaricarle. Prendi in considerazione l'API .NET. Depropria alcuni metodi ma continuano a funzionare perché i programmi codificati attorno a loro potrebbero rompersi. Una nuova versione del servizio può essere esposta in un URI diverso (v2.webservice.com) per dargli una nuova roadmap e v1 dovrebbe continuare ad essere supportato.