In genere si dovrebbe sviluppare una libreria client per i servizi REST per aiutare a prevenire rotture delle API?

Abbiamo un progetto in cui il codice dell'interfaccia utente verrà sviluppato dallo stesso team ma in una lingua diversa (Python / Django) dal livello dei servizi (REST / Java). Il codice per ogni livello esce in diversi repository di codice e può seguire diversi cicli di rilascio. Sto cercando di escogitare un processo che prevenga / riduca le rotture dei cambiamenti nel livello dei servizi dalla prospettiva del livello dell'interfaccia utente.

Ho pensato di scrivere test di integrazione a livello di interfaccia utente che eseguiremo ogni volta che creeremo l'interfaccia utente o il livello servizi (stiamo usando Jenkins come nostro strumento CI per costruire il codice che si trova in due repository Git) e se ci sono errori, quindi qualcosa nel livello dei servizi si è rotto e il commit non è accettato.

Sarebbe anche una buona idea (è una buona pratica?) Fare in modo che lo sviluppatore del livello di servizi crei e mantenga una libreria client per il servizio REST esistente nel livello dell'interfaccia utente che aggiornerà ogni volta che si verifica un cambiamento la loro API di servizio? Concepibilmente, avremmo quindi il vantaggio di un'API tipizzata staticamente su cui si basa il codice dell'interfaccia utente. Se l'API della libreria client cambia, il codice dell'interfaccia utente non verrà compilato (quindi sapremo prima che si è verificata una modifica non definitiva). Continuerei anche a eseguire i test di integrazione durante la creazione dell'interfaccia utente o del livello di servizi per verificare ulteriormente che l'integrazione tra l'interfaccia utente e i servizi funzioni ancora.

In generale, per i metodi dell'API che stanno scomparendo, selezionare una convenzione e 'deprecarli', in particolare non appena un'API di sostituzione completa è disponibile e testata. Lasciare la vecchia API in posizione (essenzialmente), ma contrassegnare i metadati della firma del metodo o inserire un evento di registrazione in modo che l'utilizzo possa essere chiaramente identificato.

La registrazione all'interno dell'API di servizio è una cosa, ma avvisare i clienti che consumano è un'altra. Per REST, non penso che ci sia una pratica solida e standard. I client API di FourSquare possono rilevare metodi obsoleti anche se il metodo chiamato ha esito positivo (codice HTTP 200, tuttavia errorType verrà impostato su "obsoleto"). Probabilmente una strategia ragionevole per fornire ai clienti consumatori l'opportunità di conoscere un metodo obsoleto all'interno dell'API senza causare interruzioni.

https://developer.foursquare.com/overview/responses

Nella guida API, suggerisci una data o crea un numero di versione in cui l'API obsoleta verrà rimossa completamente. Man mano che perfezioniamo la nostra strategia di deprecazione, vorrai avvisare i consumatori dell'API su quale sia la strategia proposta (come possono scoprire metodi deprecati, come passare all'API sostitutiva e quando l'API deprecata non sarà più disponibile se eliminato durante una pulizia dell'API) e sollecitare il feedback da parte loro per garantire che il processo sia positivo per tutti.

Il controllo delle versioni dell'API è un'altra possibilità. Quando viene distribuita una nuova versione, lasciare attiva anche la versione precedente e consentire la negoziazione tramite la richiesta. Se mantieni le ultime 2 o 3 versioni, il codice dell'interfaccia utente può essere aggiornato al suo ritmo.

Ci sono almeno tre domande alla volta, facciamole una per una

• "è una buona idea avere una libreria client per il servizio REST?"

Molto probabilmente sì, purché non si desideri che le chiamate REST arbitrarie vengano sparse direttamente attraverso tutto il codice dell'interfaccia utente.

• "è una buona idea lasciare che lo sviluppatore del livello di servizi crei e mantenga la lib?"

Dipende dalle persone nella tua squadra. Il manutentore dell'API dovrebbe conoscere sia le informazioni disponibili nel livello servizi sia i requisiti del livello interfaccia utente. Quindi può essere una persona del livello servizi o una del livello interfaccia utente oppure (a seconda delle dimensioni e di altre attività) una persona indipendentemente da entrambi i team.

• [trarremo vantaggio dal fatto che] "se l'API della libreria client cambia, il codice dell'interfaccia utente non verrà compilato"

Non hai detto che l'interfaccia utente sarà scritta in Python? Non è un linguaggio tipicamente statico, quindi non mi aspetterei un'interruzione immediata della build da una modifica dell'API. Presumo che a questo punto ti sbagli e tu abbia un'API tipizzata staticamente qui - quindi potresti ottenere alcuni vantaggi qui finché la build non si interrompe quando aggiungi solo nuove funzionalità (come nuovi parametri opzionali) all'API. In caso contrario, genererai un sacco di spese inutili per la tua squadra.