Offro ai miei clienti una piccola API di servizi Web che ho intenzione di evolvere nel tempo. Quindi ho bisogno di una sorta di controllo delle versioni, ma non riesco a trovare alcuna informazione su come si fa qualcosa del genere.Versioning API servizi Web
Esiste una best practice?
Come posso continuare ad aggiungere nuove funzionalità senza compromettere la compatibilità con i consumatori dei servizi Web?
Aggiungere il "numero di versione API" come parametro in tutte le API quindi implementare il modello di strategia nel codice del servizio Web in cui il numero di versione determina quale strategia utilizzare.
Generalmente aggiungo la stringa di versione all'URL del servizio Web, assegnandomi "endpoint con versione". Il codice che implementa questi endpoint può essere condiviso, se le differenze sono banali e possono essere gestite dallo stesso codice, o il codice può essere clonato, o da qualche parte nel mezzo.
I diversi endpoint con versione potrebbero anche utilizzare schemi XML versionati, se questo è ciò che è necessario.
Il controllo delle versioni è un argomento complesso, quindi per prima cosa è necessario definire i propri obiettivi in modo più descrittivo. Sarebbe bello dire che hai un'interfaccia che non romperai mai la compatibilità, ma a seconda di quale sia la nuova funzionalità, potrebbe non essere nemmeno possibile. Quindi ci sono diverse situazioni e diversi compromessi.
Se il tuo intento è solo fornire nuove funzionalità ai nuovi consumatori e tutti i tuoi consumatori sono consumatori diretti (senza intermediari, strutture, ecc.), Un approccio discreto all'endpoint è la scelta migliore. Ogni volta che si aggiunge una funzione che rischia una pausa, creare un nuovo endpoint, assegnargli un nuovo numero di versione e informare gli utenti di convalidarlo e cambiare le loro configurazioni. Questa strategia è abbastanza provata e vera, ma ha gli inconvenienti di mettere l'onere sui consumatori di tenersi aggiornati. Inoltre, se ci sono dipendenze tra i servizi può diventare un compito da tenere traccia. Il vantaggio è che se il codice si rompe non è (direttamente) colpa tua.
L'altra strategia principale è l'interfaccia estensibile. Ci sono tre diverse varietà qui di cui sono a conoscenza. Innanzitutto, è il tipo di interfaccia che tenta di descrivere in modo così chiaro il dominio del servizio che ogni possibile caratteristica che potresti aggiungere è in qualche modo possibile data l'interfaccia esistente. Se sembra difficile, lo è. Potresti chiamare questa l'interfaccia perfetta. Tutto è completamente descritto, ma anche l'intero dominio è completamente descritto. Il "perfetto" è in realtà solo sulla carta però.
La seconda varietà è il tipo che sembra un'interfaccia normale ma aggiunge punti di estensione generici. In WSDL questo significa xs: any, coppie nome-valore o qualcosa di simile. Si potrebbe chiamare questa interfaccia di base estendibile. Non è troppo difficile da fare, ma non è senza complicazioni. I punti di estensione possono rendere l'interfaccia più difficile da utilizzare in determinati strumenti (xs: any), o perdere esplicitamente parte della capacità di convalidare input e output (coppie nome-valore). È anche piuttosto facile abusare di quei punti di estensione in un modo che rende la versione 3 o 4 piuttosto difficile da usare.
La terza varietà è il tipo che converte l'interfaccia in un flusso di byte. Potresti chiamare queste interfacce di dio. Non sono esenti da giustificazioni, ma se ne stai usando uno, potresti chiederti perché stai utilizzando i servizi web. Forse dovresti pensare a TCP/IP non elaborato o GET/POST HTTP di base. Ma forse sei stufo della complessità di WSDL e XSD e vuoi solo ricominciare da capo ma sei legato ai servizi web per qualche motivo infrastrutturale. Tuttavia, una volta iniziato questo percorso, avrai bisogno di un modo completamente nuovo di descrivere ai tuoi consumatori come/non usare il tuo servizio, e se usi XSD per questo ... beh, in pratica sei tornato dove hai iniziato tu.
La soluzione migliore è conoscere tutte queste opzioni e avvicinarsi alla progettazione del servizio cercando innanzitutto la "perfetta interfaccia", rinunciando e aggiungendo punti di estensibilità generici. Cercare di progettare l'interfaccia perfetta ti costringerà a imparare cose che renderanno il tuo servizio migliore, non solo la tua interfaccia, ma ci vorrà del tempo, e se non limiti quel tempo in qualche modo, ci vorrà per sempre.
Un po 'meno di una vera interfaccia di Dio, c'è l'interfaccia del wrapper. Se il tuo sistema ha dei livelli, vuoi che anche la tua interfaccia sia a strati. Quando si modifica il livello B, si desidera solo modificare il livello B, non tutte le istanze nel livello C.
tutto un po 'astratto e torta nel cielo per i miei gusti. –
Come esattamente si suppone che sia più specifico, date le informazioni fornite nella domanda originale? – HDave
Una delle possibilità è progettare tutte le operazioni di servizi Web in modo che abbia un solo parametro di un tipo che eredita da un tipo che contiene il numero di versione. Questo approccio è implementato da eBay web services platform. Qualcosa di simile a quanto segue:
<xsd:complexType name="AbstractRequestType">
<xsd:attribute name="version" type="string" />
....
<xsd:complexType name="AddCustomerRequestType">
<xsd:complexContent>
<xsd:extension base="AbstractRequestType">
....
then use AddCustomerRequestType as a type of only parameter
in addCustomer web service operation.
Inoltre se si lavora su HTTP si può richiedere di aggiungere la versione come HTTP GET parametro per web service endpoint url, così sarete in grado di rilevare versione richiesta facilmente http://server/service?version=1
la strategia più comune che ho visto è alla versione del WSDL con l'aggiunta di identificazione delle versioni (tipicamente yyyy/MM[/dd]) per lo spazio dei nomi degli oggetti nel WSDL, vale a dire:
targetNamespace="http://schemas.mycompany.com/2010/01/widgets"
Questo può essere eseguito su un livello per- types/schema) o all'intero livello WSDL - <definitions> in 1.1 o <description> in 2.0.
un po 'datato, ma this link da IBM Developer Works offre il razionale di questo approccio, e in particolare quando le versioni hanno bisogno di essere incrementato:
Backwards versione compatable/variazioni non rottura:
Rottura modifiche:
Questo potrebbe funzionare solo se i servizi web di versione prendono * esattamente * la stessi argomenti, quindi vale lo stesso WSDL. Se in una nuova versione richiede l'aggiunta di un nuovo attributo, cosa fai? –