Deprecare un'API Web: best practice?

15

Alla fine è necessario deprezzare parti della tua API web pubblica. Comunque sono confuso su quale sarebbe il modo migliore per farlo. Se hai una grande base di app di terze parti, solo tirando fuori le vecchie versioni dell'API sembra che sia il modo sbagliato di farlo poiché quasi tutte le app fallirebbero durante la notte. Tuttavia, non è possibile mantenere l'API web antica disponibile per sempre in quanto potrebbe essere obsoleta o ci sono cambiamenti significativi che rendono impossibile lavorare con esso.

Quali sono le migliori pratiche per deprecare le vecchie API Web?

    
posta TheLQ 05.03.2011 - 18:28
fonte

3 risposte

15

Sembra che il poster originale abbia già efficacemente, ma disapprovato in modo informale la propria API (qualsiasi cosa venga definita "vecchia API"). Tuttavia, fino a quando non viene annunciato e agli utenti viene notificato che un'API è deprecata, non è ufficialmente deprecata.

API deprecata è una fase provvisoria e inattiva del codice. Sono gli ultimi riti. Questo è il periodo che consente ad utenti / utenti di riconfigurare le proprie app per una nuova API e fare un addio affettuoso, facendo pace con l'API. Alcune API potrebbero durare più a lungo di altre, ma a questo punto sappiamo che il loro tempo non è lungo.

L'API cancellata è un funerale di codice. Non c'è nient'altro che può fare, ma correttamente disposto e adeguatamente memorizzato.

Molti sviluppatori di API e servizi optano per i funerali del codice anziché eseguire gli ultimi riti; tuttavia, penso che sia alquanto rischioso. Se c'è stato un qualche tipo di servizio o di supporto promesso quando l'API / servizio è stato inizialmente adottato o attraverso il rinnovo, potresti voler rendere omaggio a quell'impegno per un ragionevole periodo di tempo prima di eseguire il funerale.

Per le librerie non di servizio, penso che una versione di versione principale, indipendentemente dal periodo di tempo, sia probabilmente un periodo più che accettabile ed equo di compatibilità garantita a ritroso. Oltre a ciò, dipende dall'influenza e dalle pressioni esercitate dagli utenti per estendere la sua vita oltre quel periodo. E non essere sorpreso se di tanto in tanto ci sono obiezioni a causa di insostituibili dipendenze di terze parti bloccate nel limbo e legate a certe versioni di alcune piattaforme.

Per i servizi, ho il sospetto che potreste voler considerare un periodo di sei mesi o un anno, semplicemente a causa della varianza di chi e del modo in cui un servizio può essere consumato e della corrispondente variazione del ciclo di sviluppo dal consumo del progetto al consumo progetto: molti progetti che potrebbero consumare il tuo servizio potrebbero ancora essere progettati in grande stile e potrebbero pianificare un ciclo di rilascio di più di un anno. La maggior parte delle opinioni degli sviluppatori dall'esterno suggerirebbe che coloro che hanno un programma lungo sono responsabili del rispetto dei tempi del ciclo e quei progetti che consumano molto tempo dovrebbero adottare un ciclo di rilascio più rapido, e potrebbe essere vero. Ma alla fine la data della cancellazione è qualcosa che devi negoziare con gli utenti.

Una strategia valida ma non a prova di bocciatura per la deprecazione potrebbe essere quando si annida la deprecazione, evidenziare il lasso di tempo per l'intenzione di eliminare, insieme a una richiesta di commento o obiezione in un formato di indagine delle sezioni API in questione. Se non si dispone di un elenco di contatti degli utenti poiché il servizio opera con accesso [semi] anonimo, è possibile considerare la possibilità di consultare i registri per utenti frequenti e attivi e inviare la notifica all'amministratore dell'host o del dominio per inoltrare come ritengono opportuno.

    
risposta data 06.03.2011 - 02:22
fonte
6

La maggior parte delle API Web che uso (da aziende come Google, Yahoo! e Microsoft) hanno un periodo di "tramonto". Gli sviluppatori sono informati entro un tempo ragionevole (ad esempio 3-6 mesi) delle funzionalità che saranno ammortizzate in modo da concedere loro un sacco di tempo per effettuare l'upgrade in anticipo.

Puoi aggiungere i dettagli dei periodi di tramonto nei tuoi Termini di servizio o altra documentazione in modo che le persone siano consapevoli di come funziona. Ciò significherebbe che quando qualcuno decide di utilizzare la tua API saprà quali programmi devono essere utilizzati. Ad esempio, potresti informare le persone che dovranno aggiornare il loro sistema una volta all'anno e avere 4 mesi di preavviso per farlo.

È anche una buona idea usare la numerazione delle versioni in modo da poter dire che, ad esempio, "la versione 3 sarà presto ammortizzata, quindi assicurati che il tuo codice funzioni con la versione 4" ecc. In questo modo le persone sanno che se la loro applicazione lavorando con la versione 4, sono pronti per il tramonto.

    
risposta data 05.03.2011 - 18:49
fonte
0

Oltre alle risposte esistenti, dovresti fornire una sostituzione drop-in o un piano di migrazione quando rimuovi qualcosa, in modo che gli utenti possano aggiornare il loro codice.

Cerca di evitare di rimuovere funzionalità senza fornire un'alternativa: ciò renderebbe infelici alcuni dei tuoi utenti.

    
risposta data 13.07.2014 - 11:25
fonte

Leggi altre domande sui tag