Pratiche migliori per la versioning delle API RESTful: Perché la v1 è la numero 1
Chris McFadden
24 mag 2017
1 min read
Punti Chiave
La versioning API previene cambiamenti di rottura e preserva la fiducia tra i fornitori di API e gli sviluppatori.
Chiare convenzioni di versioning aiutano ad evitare un mix caotico di versioni attraverso i punti finali.
API RESTful abbinate a URI di versione semplici ed espliciti mantengono le integrazioni intuitive per gli sviluppatori.
I gruppi di governance assicurano coerenza tra i team, prevenendo cambiamenti di rottura accidentali.
Non tutti i cambiamenti richiedono una nuova versione — solo quelli che rompono le integrazioni esistenti.
Una buona documentazione è essenziale per evitare confusione e prevenire cambiamenti di rottura involontari.
Separare il deployment dal rilascio consente ai team di testare e affinare in sicurezza i punti finali prima di annunciarli.
Quando i cambiamenti di rottura sono inevitabili, devono essere valutati e comunicati con attenzione.
Punti salienti del Q&A
Perché è importante il versioning delle API?
Previene cambiamenti inaspettati e interruzioni per gli sviluppatori che si integrano con la tua API, protegge la fiducia e garantisce la stabilità a lungo termine per le applicazioni che si basano su comportamenti coerenti.
Cosa sono le modifiche radicali in un'API?
Qualsiasi modifica che cambia il comportamento delle integrazioni esistenti — come la rimozione di endpoint, la modifica dei valori predefiniti, l'aggiunta di campi obbligatori o la modifica dei formati di risposta.
Perché SparkPost ha scelto REST come base per la propria API?
L'uso di HTTP e JSON da parte di REST rende facile per gli sviluppatori di diverse lingue (PHP, Ruby, Java, ecc.) integrarsi senza la necessità di conoscenze specialistiche dei sistemi sottostanti.
Come ha deciso SparkPost il suo metodo di versioning?
Hanno valutato il versioning basato sull'intestazione Accept rispetto al versioning basato su URI e hanno scelto il versioning basato su URI perché è esplicito, semplice e più amichevole per gli sviluppatori.
Quale ruolo svolge un gruppo di governance delle API?
Stabilisci standard, applica coerenza e previene che i team introducano modifiche che confliggono con le convenzioni o rompono la compatibilità.
Quali tipi di modifiche non sono considerate breaking?
Aggiunta di nuovi parametri opzionali, introduzione di nuovi endpoint, aggiunta di nuove chiavi nei payload JSON o modifica di endpoint non pubblici: qualsiasi cosa che non interrompa il comportamento esistente.
Quali cambiamenti sono considerati incompatibili?
Aggiungendo parametri richiesti, rimuovendo endpoint, cambiando comportamenti predefiniti, modificando la struttura della risposta o introducendo campi JSON richiesti.
Perché è essenziale una documentazione accurata?
Previene cambiamenti imprevisti, aiuta gli sviluppatori a comprendere il comportamento e garantisce che i team aggiornino l'API in modo affidabile. SparkPost ha utilizzato Markdown (API Blueprint) e GitHub per mantenere chiarezza e apertura.
Qual è il vantaggio di separare il deployment dal rilascio?
I team possono continuamente distribuire nuovi endpoint o miglioramenti internamente, testarli in flussi di lavoro reali, affinare i comportamenti e rilasciare pubblicamente solo una volta stabilizzati, evitando esposizioni premature e potenzialmente distruttive.
Cosa succede se diventa necessario un cambiamento drastico?
Deve essere raro, giustificato da benefici chiari, valutato attentamente per l'impatto sugli utenti e comunicato in modo esaustivo. Esempio: regolare l'API di soppressione solo dopo aver confermato un effetto minimo e fornendo avviso.
Quindi, quanto può essere difficile versionare un API? La verità è che non lo è, ma ciò che è difficile è mantenere un po' di sanità mentale evitando di devolvere in un numero vertiginoso di versioni e sottoversioni applicate attraverso dozzine di endpoint API con compatibilità poco chiare.
Quindi, quanto può essere difficile versionare un API? La verità è che non lo è, ma ciò che è difficile è mantenere un po' di sanità mentale evitando di devolvere in un numero vertiginoso di versioni e sottoversioni applicate attraverso dozzine di endpoint API con compatibilità poco chiare.
Quindi, quanto può essere difficile versionare un API? La verità è che non lo è, ma ciò che è difficile è mantenere un po' di sanità mentale evitando di devolvere in un numero vertiginoso di versioni e sottoversioni applicate attraverso dozzine di endpoint API con compatibilità poco chiare.
Doh!
È giusto ammettere che ci sono stati momenti in cui non abbiamo rispettato i nostri ideali di “nessun cambiamento che rompa” e questi sono degni di essere appresi. In un'occasione abbiamo deciso che sarebbe stato meglio per gli utenti se una certa proprietà fosse impostata su true invece che su false. Dopo aver implementato la modifica abbiamo ricevuto diverse lamentele da parte degli utenti poiché il comportamento era cambiato inaspettatamente. Abbiamo annullato la modifica e aggiunto un'impostazione a livello di account – un approccio sicuramente più user friendly.
Occasionalmente siamo tentati di introdurre cambiamenti che rompono a causa di correzioni di bug. Tuttavia, abbiamo deciso di lasciare queste peculiarità così come sono invece di rischiare di rompere le integrazioni dei clienti per il bene della coerenza.
Ci sono rari casi in cui abbiamo preso la decisione seria di apportare un cambiamento che rompe – come deprecare una risorsa o un metodo API – nell'interesse della comunità degli utenti più ampia e solo dopo aver confermato che l'impatto sugli utenti è minimo o nullo. Ad esempio, abbiamo deliberatamente scelto di modificare il comportamento della risposta dell'API di Soppressione ma solo dopo aver valutato attentamente i benefici e gli impatti sulla comunità e comunicato con attenzione il cambiamento ai nostri utenti. Tuttavia, non introducemmo mai un cambiamento che abbia una possibilità remota di influire direttamente sull'invio delle email di produzione di un utente.
È giusto ammettere che ci sono stati momenti in cui non abbiamo rispettato i nostri ideali di “nessun cambiamento che rompa” e questi sono degni di essere appresi. In un'occasione abbiamo deciso che sarebbe stato meglio per gli utenti se una certa proprietà fosse impostata su true invece che su false. Dopo aver implementato la modifica abbiamo ricevuto diverse lamentele da parte degli utenti poiché il comportamento era cambiato inaspettatamente. Abbiamo annullato la modifica e aggiunto un'impostazione a livello di account – un approccio sicuramente più user friendly.
Occasionalmente siamo tentati di introdurre cambiamenti che rompono a causa di correzioni di bug. Tuttavia, abbiamo deciso di lasciare queste peculiarità così come sono invece di rischiare di rompere le integrazioni dei clienti per il bene della coerenza.
Ci sono rari casi in cui abbiamo preso la decisione seria di apportare un cambiamento che rompe – come deprecare una risorsa o un metodo API – nell'interesse della comunità degli utenti più ampia e solo dopo aver confermato che l'impatto sugli utenti è minimo o nullo. Ad esempio, abbiamo deliberatamente scelto di modificare il comportamento della risposta dell'API di Soppressione ma solo dopo aver valutato attentamente i benefici e gli impatti sulla comunità e comunicato con attenzione il cambiamento ai nostri utenti. Tuttavia, non introducemmo mai un cambiamento che abbia una possibilità remota di influire direttamente sull'invio delle email di produzione di un utente.
È giusto ammettere che ci sono stati momenti in cui non abbiamo rispettato i nostri ideali di “nessun cambiamento che rompa” e questi sono degni di essere appresi. In un'occasione abbiamo deciso che sarebbe stato meglio per gli utenti se una certa proprietà fosse impostata su true invece che su false. Dopo aver implementato la modifica abbiamo ricevuto diverse lamentele da parte degli utenti poiché il comportamento era cambiato inaspettatamente. Abbiamo annullato la modifica e aggiunto un'impostazione a livello di account – un approccio sicuramente più user friendly.
Occasionalmente siamo tentati di introdurre cambiamenti che rompono a causa di correzioni di bug. Tuttavia, abbiamo deciso di lasciare queste peculiarità così come sono invece di rischiare di rompere le integrazioni dei clienti per il bene della coerenza.
Ci sono rari casi in cui abbiamo preso la decisione seria di apportare un cambiamento che rompe – come deprecare una risorsa o un metodo API – nell'interesse della comunità degli utenti più ampia e solo dopo aver confermato che l'impatto sugli utenti è minimo o nullo. Ad esempio, abbiamo deliberatamente scelto di modificare il comportamento della risposta dell'API di Soppressione ma solo dopo aver valutato attentamente i benefici e gli impatti sulla comunità e comunicato con attenzione il cambiamento ai nostri utenti. Tuttavia, non introducemmo mai un cambiamento che abbia una possibilità remota di influire direttamente sull'invio delle email di produzione di un utente.
Cambiamenti drastici cattivi! Versioning API buono!
Come chiunque abbia costruito o utilizzi regolarmente un'API si rende conto prima o poi, le modifiche che rompono la compatibilità sono molto dannose e possono essere un serio difetto in un'API altrimenti utile. Una modifica che rompe la compatibilità è un cambiamento nel comportamento di un'API che può interrompere l'integrazione di un utente e causare molta frustrazione e perdita di fiducia tra il fornitore dell'API e l'utente. Le modifiche che rompono la compatibilità richiedono che gli utenti vengano avvisati in anticipo (con annesse scuse) piuttosto che una modifica che appare all'improvviso, come una nuova funzione deliziosa. Il modo per evitare quella frustrazione è versionare un'API con garantire da parte del proprietario dell'API che non ci saranno cambiamenti sorprendenti introdotti all'interno di una singola versione.
Quanto può essere difficile versionare un'API? La verità è che non è difficile, ma ciò che è difficile è mantenere un certo equilibrio evitando di cadere in un numero vertiginoso di versioni e sottoversioni applicate su dozzine di endpoint API con compatibilità poco chiare.
Abbiamo introdotto v1 dell'API tre anni fa e non ci rendevamo conto che sarebbe andata forte fino ad oggi. Quindi, come abbiamo continuato a fornire la migliore API per la consegna di email per oltre due anni ma mantenendo comunque la stessa versione dell'API? Questa stabilità è cruciale per gli sviluppatori che costruiscono applicazioni con API email in infrastrutture cloud, dove l'affidabilità e la coerenza sono fondamentali. Anche se ci sono molte opinioni diverse su come versionare le API REST, spero che la storia della nostra umile ma potente v1 possa guidarti verso l'illuminazione nella versioning delle API.
Come chiunque abbia costruito o utilizzi regolarmente un'API si rende conto prima o poi, le modifiche che rompono la compatibilità sono molto dannose e possono essere un serio difetto in un'API altrimenti utile. Una modifica che rompe la compatibilità è un cambiamento nel comportamento di un'API che può interrompere l'integrazione di un utente e causare molta frustrazione e perdita di fiducia tra il fornitore dell'API e l'utente. Le modifiche che rompono la compatibilità richiedono che gli utenti vengano avvisati in anticipo (con annesse scuse) piuttosto che una modifica che appare all'improvviso, come una nuova funzione deliziosa. Il modo per evitare quella frustrazione è versionare un'API con garantire da parte del proprietario dell'API che non ci saranno cambiamenti sorprendenti introdotti all'interno di una singola versione.
Quanto può essere difficile versionare un'API? La verità è che non è difficile, ma ciò che è difficile è mantenere un certo equilibrio evitando di cadere in un numero vertiginoso di versioni e sottoversioni applicate su dozzine di endpoint API con compatibilità poco chiare.
Abbiamo introdotto v1 dell'API tre anni fa e non ci rendevamo conto che sarebbe andata forte fino ad oggi. Quindi, come abbiamo continuato a fornire la migliore API per la consegna di email per oltre due anni ma mantenendo comunque la stessa versione dell'API? Questa stabilità è cruciale per gli sviluppatori che costruiscono applicazioni con API email in infrastrutture cloud, dove l'affidabilità e la coerenza sono fondamentali. Anche se ci sono molte opinioni diverse su come versionare le API REST, spero che la storia della nostra umile ma potente v1 possa guidarti verso l'illuminazione nella versioning delle API.
Come chiunque abbia costruito o utilizzi regolarmente un'API si rende conto prima o poi, le modifiche che rompono la compatibilità sono molto dannose e possono essere un serio difetto in un'API altrimenti utile. Una modifica che rompe la compatibilità è un cambiamento nel comportamento di un'API che può interrompere l'integrazione di un utente e causare molta frustrazione e perdita di fiducia tra il fornitore dell'API e l'utente. Le modifiche che rompono la compatibilità richiedono che gli utenti vengano avvisati in anticipo (con annesse scuse) piuttosto che una modifica che appare all'improvviso, come una nuova funzione deliziosa. Il modo per evitare quella frustrazione è versionare un'API con garantire da parte del proprietario dell'API che non ci saranno cambiamenti sorprendenti introdotti all'interno di una singola versione.
Quanto può essere difficile versionare un'API? La verità è che non è difficile, ma ciò che è difficile è mantenere un certo equilibrio evitando di cadere in un numero vertiginoso di versioni e sottoversioni applicate su dozzine di endpoint API con compatibilità poco chiare.
Abbiamo introdotto v1 dell'API tre anni fa e non ci rendevamo conto che sarebbe andata forte fino ad oggi. Quindi, come abbiamo continuato a fornire la migliore API per la consegna di email per oltre due anni ma mantenendo comunque la stessa versione dell'API? Questa stabilità è cruciale per gli sviluppatori che costruiscono applicazioni con API email in infrastrutture cloud, dove l'affidabilità e la coerenza sono fondamentali. Anche se ci sono molte opinioni diverse su come versionare le API REST, spero che la storia della nostra umile ma potente v1 possa guidarti verso l'illuminazione nella versioning delle API.
Il riposo è il migliore
La SparkPost API ha origine quando eravamo Message Systems, prima delle nostre avventure nel cloud. A quel tempo eravamo impegnati a fare le ultime preparazioni per il lancio beta di Momentum 4. Questo rappresentava un importante aggiornamento rispetto alla versione 3.x, il nostro MTA leader di mercato on-premise. Momentum 4 includeva un'interfaccia utente completamente nuova, analisi in tempo reale e, soprattutto, una nuova API web per l'iniezione e generazione dei messaggi, gestione dei modelli e acquisizione delle metriche email. La nostra visione era di un'architettura API-first – dove anche l'interfaccia utente avrebbe interagito con i punti finali dell'API.
Una delle decisioni più precoci e migliori che abbiamo preso è stata adottare uno stile RESTful. Poiché la fine degli anni 2000 rappresenta il trasferimento di stato rappresentazionale (REST), le API web basate su questo sono diventate lo standard de facto delle API cloud. Utilizzare HTTP e JSON rende facile per gli sviluppatori, indipendentemente dal linguaggio di programmazione utilizzato – PHP, Ruby e Java – integrarsi con la nostra API senza conoscere o preoccuparsi della nostra tecnologia sottostante. Tuttavia, costruire API cloud-native su scala può presentare sfide infrastrutturali inaspettate, come i limiti di scalabilità del DNS che abbiamo incontrato in AWS quando gestivamo un traffico API ad alto volume.
Scegliere di utilizzare l'architettura RESTful è stato facile. Scegliere una convenzione di versioning non è stato così semplice. Inizialmente abbiamo rimandato la questione del versioning non versionando affatto la beta. Tuttavia, dopo un paio di mesi la beta era nelle mani di alcuni clienti e abbiamo iniziato a costruire il nostro servizio cloud. Era ora di versionare. Abbiamo valutato due convenzioni di versioning.
Approccio al versioning | Come funziona | Compensazione |
|---|---|---|
Versioning URI | Versione inclusa nel percorso dell'endpoint | Esplicito e facile da comprendere |
Versioning header di accettazione | Versione passata tramite header HTTP | Meno visibile, più complesso per gli sviluppatori |
Il primo era mettere il versioning direttamente nell'URI e il secondo era usare un header di accettazione. La prima opzione è più esplicita e meno complicata, il che è più facile per gli sviluppatori. Poiché amiamo gli sviluppatori, è stata la scelta logica.
La SparkPost API ha origine quando eravamo Message Systems, prima delle nostre avventure nel cloud. A quel tempo eravamo impegnati a fare le ultime preparazioni per il lancio beta di Momentum 4. Questo rappresentava un importante aggiornamento rispetto alla versione 3.x, il nostro MTA leader di mercato on-premise. Momentum 4 includeva un'interfaccia utente completamente nuova, analisi in tempo reale e, soprattutto, una nuova API web per l'iniezione e generazione dei messaggi, gestione dei modelli e acquisizione delle metriche email. La nostra visione era di un'architettura API-first – dove anche l'interfaccia utente avrebbe interagito con i punti finali dell'API.
Una delle decisioni più precoci e migliori che abbiamo preso è stata adottare uno stile RESTful. Poiché la fine degli anni 2000 rappresenta il trasferimento di stato rappresentazionale (REST), le API web basate su questo sono diventate lo standard de facto delle API cloud. Utilizzare HTTP e JSON rende facile per gli sviluppatori, indipendentemente dal linguaggio di programmazione utilizzato – PHP, Ruby e Java – integrarsi con la nostra API senza conoscere o preoccuparsi della nostra tecnologia sottostante. Tuttavia, costruire API cloud-native su scala può presentare sfide infrastrutturali inaspettate, come i limiti di scalabilità del DNS che abbiamo incontrato in AWS quando gestivamo un traffico API ad alto volume.
Scegliere di utilizzare l'architettura RESTful è stato facile. Scegliere una convenzione di versioning non è stato così semplice. Inizialmente abbiamo rimandato la questione del versioning non versionando affatto la beta. Tuttavia, dopo un paio di mesi la beta era nelle mani di alcuni clienti e abbiamo iniziato a costruire il nostro servizio cloud. Era ora di versionare. Abbiamo valutato due convenzioni di versioning.
Approccio al versioning | Come funziona | Compensazione |
|---|---|---|
Versioning URI | Versione inclusa nel percorso dell'endpoint | Esplicito e facile da comprendere |
Versioning header di accettazione | Versione passata tramite header HTTP | Meno visibile, più complesso per gli sviluppatori |
Il primo era mettere il versioning direttamente nell'URI e il secondo era usare un header di accettazione. La prima opzione è più esplicita e meno complicata, il che è più facile per gli sviluppatori. Poiché amiamo gli sviluppatori, è stata la scelta logica.
La SparkPost API ha origine quando eravamo Message Systems, prima delle nostre avventure nel cloud. A quel tempo eravamo impegnati a fare le ultime preparazioni per il lancio beta di Momentum 4. Questo rappresentava un importante aggiornamento rispetto alla versione 3.x, il nostro MTA leader di mercato on-premise. Momentum 4 includeva un'interfaccia utente completamente nuova, analisi in tempo reale e, soprattutto, una nuova API web per l'iniezione e generazione dei messaggi, gestione dei modelli e acquisizione delle metriche email. La nostra visione era di un'architettura API-first – dove anche l'interfaccia utente avrebbe interagito con i punti finali dell'API.
Una delle decisioni più precoci e migliori che abbiamo preso è stata adottare uno stile RESTful. Poiché la fine degli anni 2000 rappresenta il trasferimento di stato rappresentazionale (REST), le API web basate su questo sono diventate lo standard de facto delle API cloud. Utilizzare HTTP e JSON rende facile per gli sviluppatori, indipendentemente dal linguaggio di programmazione utilizzato – PHP, Ruby e Java – integrarsi con la nostra API senza conoscere o preoccuparsi della nostra tecnologia sottostante. Tuttavia, costruire API cloud-native su scala può presentare sfide infrastrutturali inaspettate, come i limiti di scalabilità del DNS che abbiamo incontrato in AWS quando gestivamo un traffico API ad alto volume.
Scegliere di utilizzare l'architettura RESTful è stato facile. Scegliere una convenzione di versioning non è stato così semplice. Inizialmente abbiamo rimandato la questione del versioning non versionando affatto la beta. Tuttavia, dopo un paio di mesi la beta era nelle mani di alcuni clienti e abbiamo iniziato a costruire il nostro servizio cloud. Era ora di versionare. Abbiamo valutato due convenzioni di versioning.
Approccio al versioning | Come funziona | Compensazione |
|---|---|---|
Versioning URI | Versione inclusa nel percorso dell'endpoint | Esplicito e facile da comprendere |
Versioning header di accettazione | Versione passata tramite header HTTP | Meno visibile, più complesso per gli sviluppatori |
Il primo era mettere il versioning direttamente nell'URI e il secondo era usare un header di accettazione. La prima opzione è più esplicita e meno complicata, il che è più facile per gli sviluppatori. Poiché amiamo gli sviluppatori, è stata la scelta logica.
Governance delle API
Con una convenzione di versioning selezionata, avevamo più domande. Quando dovremmo aumentare la versione? Cos'è un cambiamento distruttivo? Dobbiamo rigenerare l'intera API o solo determinati endpoint? Presso SparkPost, abbiamo più team che lavorano su diverse parti della nostra API. All'interno di quei team, le persone lavorano su diversi endpoint in momenti diversi. Pertanto, è molto importante che la nostra API sia coerente nell'uso delle convenzioni. Questo era più grande del versioning.
Abbiamo istituito un gruppo di governance che include ingegneri rappresentanti di ciascun team, un membro del team di gestione prodotto e il nostro CTO. Questo gruppo è responsabile di stabilire, documentare e far rispettare le nostre convenzioni API tra tutti i team. Un canale Slack per la governance delle API è anche utile per dibattiti vivaci sull'argomento.
Il gruppo di governance ha identificato una serie di modi in cui le modifiche possono essere introdotte nell'API che sono vantaggiose per l'utente e non costituiscono un cambiamento distruttivo.
Tipo di cambiamento | Considerato distruttivo? | Motivo |
|---|---|---|
Nuova risorsa o endpoint | No | Non influisce sulle integrazioni esistenti |
Nuovo parametro facoltativo | No | Le richieste esistenti rimangono valide |
Nuova chiave JSON facoltativa | No | I client possono ignorarla in sicurezza |
Nuovo campo di risposta | No | Compatibile con le versioni precedenti per i consumatori |
Nuovo parametro obbligatorio | Sì | Interrompe le richieste esistenti |
Nuova chiave POST obbligatoria | Sì | Invalida i payload esistenti |
Rimozione di un endpoint | Sì | Le integrazioni esistenti non funzionano |
Cambiare il comportamento predefinito | Sì | Modifica i risultati attesi |
Questi includono:
Una nuova risorsa o endpoint API
Un nuovo parametro facoltativo
Una modifica a un endpoint API non pubblico
Una nuova chiave facoltativa nel corpo JSON POST
Una nuova chiave restituita nel corpo di risposta JSON
Al contrario, un cambiamento distruttivo includeva tutto ciò che potrebbe rompere l'integrazione di un utente, come:
Un nuovo parametro obbligatorio
Una nuova chiave obbligatoria nei corpi POST
Rimozione di un endpoint esistente
Rimozione di un metodo di richiesta di endpoint esistente
Un comportamento interno materialmente diverso di una chiamata API – come un cambiamento nel comportamento predefinito.
Con una convenzione di versioning selezionata, avevamo più domande. Quando dovremmo aumentare la versione? Cos'è un cambiamento distruttivo? Dobbiamo rigenerare l'intera API o solo determinati endpoint? Presso SparkPost, abbiamo più team che lavorano su diverse parti della nostra API. All'interno di quei team, le persone lavorano su diversi endpoint in momenti diversi. Pertanto, è molto importante che la nostra API sia coerente nell'uso delle convenzioni. Questo era più grande del versioning.
Abbiamo istituito un gruppo di governance che include ingegneri rappresentanti di ciascun team, un membro del team di gestione prodotto e il nostro CTO. Questo gruppo è responsabile di stabilire, documentare e far rispettare le nostre convenzioni API tra tutti i team. Un canale Slack per la governance delle API è anche utile per dibattiti vivaci sull'argomento.
Il gruppo di governance ha identificato una serie di modi in cui le modifiche possono essere introdotte nell'API che sono vantaggiose per l'utente e non costituiscono un cambiamento distruttivo.
Tipo di cambiamento | Considerato distruttivo? | Motivo |
|---|---|---|
Nuova risorsa o endpoint | No | Non influisce sulle integrazioni esistenti |
Nuovo parametro facoltativo | No | Le richieste esistenti rimangono valide |
Nuova chiave JSON facoltativa | No | I client possono ignorarla in sicurezza |
Nuovo campo di risposta | No | Compatibile con le versioni precedenti per i consumatori |
Nuovo parametro obbligatorio | Sì | Interrompe le richieste esistenti |
Nuova chiave POST obbligatoria | Sì | Invalida i payload esistenti |
Rimozione di un endpoint | Sì | Le integrazioni esistenti non funzionano |
Cambiare il comportamento predefinito | Sì | Modifica i risultati attesi |
Questi includono:
Una nuova risorsa o endpoint API
Un nuovo parametro facoltativo
Una modifica a un endpoint API non pubblico
Una nuova chiave facoltativa nel corpo JSON POST
Una nuova chiave restituita nel corpo di risposta JSON
Al contrario, un cambiamento distruttivo includeva tutto ciò che potrebbe rompere l'integrazione di un utente, come:
Un nuovo parametro obbligatorio
Una nuova chiave obbligatoria nei corpi POST
Rimozione di un endpoint esistente
Rimozione di un metodo di richiesta di endpoint esistente
Un comportamento interno materialmente diverso di una chiamata API – come un cambiamento nel comportamento predefinito.
Con una convenzione di versioning selezionata, avevamo più domande. Quando dovremmo aumentare la versione? Cos'è un cambiamento distruttivo? Dobbiamo rigenerare l'intera API o solo determinati endpoint? Presso SparkPost, abbiamo più team che lavorano su diverse parti della nostra API. All'interno di quei team, le persone lavorano su diversi endpoint in momenti diversi. Pertanto, è molto importante che la nostra API sia coerente nell'uso delle convenzioni. Questo era più grande del versioning.
Abbiamo istituito un gruppo di governance che include ingegneri rappresentanti di ciascun team, un membro del team di gestione prodotto e il nostro CTO. Questo gruppo è responsabile di stabilire, documentare e far rispettare le nostre convenzioni API tra tutti i team. Un canale Slack per la governance delle API è anche utile per dibattiti vivaci sull'argomento.
Il gruppo di governance ha identificato una serie di modi in cui le modifiche possono essere introdotte nell'API che sono vantaggiose per l'utente e non costituiscono un cambiamento distruttivo.
Tipo di cambiamento | Considerato distruttivo? | Motivo |
|---|---|---|
Nuova risorsa o endpoint | No | Non influisce sulle integrazioni esistenti |
Nuovo parametro facoltativo | No | Le richieste esistenti rimangono valide |
Nuova chiave JSON facoltativa | No | I client possono ignorarla in sicurezza |
Nuovo campo di risposta | No | Compatibile con le versioni precedenti per i consumatori |
Nuovo parametro obbligatorio | Sì | Interrompe le richieste esistenti |
Nuova chiave POST obbligatoria | Sì | Invalida i payload esistenti |
Rimozione di un endpoint | Sì | Le integrazioni esistenti non funzionano |
Cambiare il comportamento predefinito | Sì | Modifica i risultati attesi |
Questi includono:
Una nuova risorsa o endpoint API
Un nuovo parametro facoltativo
Una modifica a un endpoint API non pubblico
Una nuova chiave facoltativa nel corpo JSON POST
Una nuova chiave restituita nel corpo di risposta JSON
Al contrario, un cambiamento distruttivo includeva tutto ciò che potrebbe rompere l'integrazione di un utente, come:
Un nuovo parametro obbligatorio
Una nuova chiave obbligatoria nei corpi POST
Rimozione di un endpoint esistente
Rimozione di un metodo di richiesta di endpoint esistente
Un comportamento interno materialmente diverso di una chiamata API – come un cambiamento nel comportamento predefinito.
Il Grande 1.0
Come abbiamo documentato e discusso queste convenzioni, siamo anche giunti alla conclusione che fosse nel migliore interesse di tutti (compreso il nostro!) evitare di apportare modifiche incompatibili all'API poiché gestire più versioni comporta un notevole sovraccarico. Abbiamo deciso che c'erano alcune cose che dovevamo sistemare con la nostra API prima di impegnarci per la “v1”.
Inviare una semplice email richiedeva troppo impegno. Per “mantenere le cose semplici semplici” abbiamo aggiornato il corpo POST per garantire che siano accommodate sia situazioni semplici che complesse. Il nuovo formato era anche più a prova di futuro. Inoltre, abbiamo affrontato un problema con l'endpoint Metrics. Questo endpoint utilizzava un parametro “group_by” che cambiava il formato del corpo della risposta GET in modo tale che la prima chiave sarebbe stata il valore del parametro group by. Ciò non sembrava molto RESTful, quindi abbiamo suddiviso ciascun group by in un endpoint separato. Infine, abbiamo esaminato ciascun endpoint e apportato piccole modifiche qua e là per garantire che fossero conformi agli standard.
Come abbiamo documentato e discusso queste convenzioni, siamo anche giunti alla conclusione che fosse nel migliore interesse di tutti (compreso il nostro!) evitare di apportare modifiche incompatibili all'API poiché gestire più versioni comporta un notevole sovraccarico. Abbiamo deciso che c'erano alcune cose che dovevamo sistemare con la nostra API prima di impegnarci per la “v1”.
Inviare una semplice email richiedeva troppo impegno. Per “mantenere le cose semplici semplici” abbiamo aggiornato il corpo POST per garantire che siano accommodate sia situazioni semplici che complesse. Il nuovo formato era anche più a prova di futuro. Inoltre, abbiamo affrontato un problema con l'endpoint Metrics. Questo endpoint utilizzava un parametro “group_by” che cambiava il formato del corpo della risposta GET in modo tale che la prima chiave sarebbe stata il valore del parametro group by. Ciò non sembrava molto RESTful, quindi abbiamo suddiviso ciascun group by in un endpoint separato. Infine, abbiamo esaminato ciascun endpoint e apportato piccole modifiche qua e là per garantire che fossero conformi agli standard.
Come abbiamo documentato e discusso queste convenzioni, siamo anche giunti alla conclusione che fosse nel migliore interesse di tutti (compreso il nostro!) evitare di apportare modifiche incompatibili all'API poiché gestire più versioni comporta un notevole sovraccarico. Abbiamo deciso che c'erano alcune cose che dovevamo sistemare con la nostra API prima di impegnarci per la “v1”.
Inviare una semplice email richiedeva troppo impegno. Per “mantenere le cose semplici semplici” abbiamo aggiornato il corpo POST per garantire che siano accommodate sia situazioni semplici che complesse. Il nuovo formato era anche più a prova di futuro. Inoltre, abbiamo affrontato un problema con l'endpoint Metrics. Questo endpoint utilizzava un parametro “group_by” che cambiava il formato del corpo della risposta GET in modo tale che la prima chiave sarebbe stata il valore del parametro group by. Ciò non sembrava molto RESTful, quindi abbiamo suddiviso ciascun group by in un endpoint separato. Infine, abbiamo esaminato ciascun endpoint e apportato piccole modifiche qua e là per garantire che fossero conformi agli standard.
Documentazione Accurata
È importante avere una documentazione API accurata e utilizzabile per evitare cambiamenti che possano risultare dannosi, siano essi intenzionali o non intenzionali. Abbiamo deciso di adottare un approccio semplice alla documentazione API sfruttando un linguaggio Markdown chiamato API Blueprint e gestire i nostri doc su Github. La nostra comunità contribuisce e migliora questi documenti open source. Manteniamo anche un insieme non pubblico di documenti su Github per le API e gli endpoint interni.
Inizialmente, abbiamo pubblicato i nostri documenti su Apiary, uno strumento fantastico per prototipare e pubblicare documentazione API. Tuttavia, incorporare Apiary nel nostro sito web non funziona sui dispositivi mobili, quindi ora utilizziamo Jekyll per generare documenti statici. La nostra ultima documentazione API di SparkPost ora si carica rapidamente e funziona bene sui dispositivi mobili, il che è importante per gli sviluppatori che non sono sempre seduti al computer.
È importante avere una documentazione API accurata e utilizzabile per evitare cambiamenti che possano risultare dannosi, siano essi intenzionali o non intenzionali. Abbiamo deciso di adottare un approccio semplice alla documentazione API sfruttando un linguaggio Markdown chiamato API Blueprint e gestire i nostri doc su Github. La nostra comunità contribuisce e migliora questi documenti open source. Manteniamo anche un insieme non pubblico di documenti su Github per le API e gli endpoint interni.
Inizialmente, abbiamo pubblicato i nostri documenti su Apiary, uno strumento fantastico per prototipare e pubblicare documentazione API. Tuttavia, incorporare Apiary nel nostro sito web non funziona sui dispositivi mobili, quindi ora utilizziamo Jekyll per generare documenti statici. La nostra ultima documentazione API di SparkPost ora si carica rapidamente e funziona bene sui dispositivi mobili, il che è importante per gli sviluppatori che non sono sempre seduti al computer.
È importante avere una documentazione API accurata e utilizzabile per evitare cambiamenti che possano risultare dannosi, siano essi intenzionali o non intenzionali. Abbiamo deciso di adottare un approccio semplice alla documentazione API sfruttando un linguaggio Markdown chiamato API Blueprint e gestire i nostri doc su Github. La nostra comunità contribuisce e migliora questi documenti open source. Manteniamo anche un insieme non pubblico di documenti su Github per le API e gli endpoint interni.
Inizialmente, abbiamo pubblicato i nostri documenti su Apiary, uno strumento fantastico per prototipare e pubblicare documentazione API. Tuttavia, incorporare Apiary nel nostro sito web non funziona sui dispositivi mobili, quindi ora utilizziamo Jekyll per generare documenti statici. La nostra ultima documentazione API di SparkPost ora si carica rapidamente e funziona bene sui dispositivi mobili, il che è importante per gli sviluppatori che non sono sempre seduti al computer.
Separare il Deployment dal Release
Abbiamo imparato presto il prezioso trucco di separare un deployment da un rilascio. In questo modo è possibile distribuire frequentemente le modifiche quando sono pronte tramite consegna e distribuzione continue, ma non le annunciamo o documentiamo pubblicamente allo stesso tempo. Non è raro per noi distribuire un nuovo endpoint API o un miglioramento a un endpoint API esistente e utilizzarlo all'interno dell'interfaccia utente o con strumenti interni prima di documentarlo e supportarlo pubblicamente. In questo modo possiamo apportare alcune modifiche per l'usabilità o la conformità agli standard senza preoccuparci di apportare un cambiamento temuto. Una volta che siamo soddisfatti del cambiamento, lo aggiungiamo alla nostra documentazione pubblica.
Abbiamo imparato presto il prezioso trucco di separare un deployment da un rilascio. In questo modo è possibile distribuire frequentemente le modifiche quando sono pronte tramite consegna e distribuzione continue, ma non le annunciamo o documentiamo pubblicamente allo stesso tempo. Non è raro per noi distribuire un nuovo endpoint API o un miglioramento a un endpoint API esistente e utilizzarlo all'interno dell'interfaccia utente o con strumenti interni prima di documentarlo e supportarlo pubblicamente. In questo modo possiamo apportare alcune modifiche per l'usabilità o la conformità agli standard senza preoccuparci di apportare un cambiamento temuto. Una volta che siamo soddisfatti del cambiamento, lo aggiungiamo alla nostra documentazione pubblica.
Abbiamo imparato presto il prezioso trucco di separare un deployment da un rilascio. In questo modo è possibile distribuire frequentemente le modifiche quando sono pronte tramite consegna e distribuzione continue, ma non le annunciamo o documentiamo pubblicamente allo stesso tempo. Non è raro per noi distribuire un nuovo endpoint API o un miglioramento a un endpoint API esistente e utilizzarlo all'interno dell'interfaccia utente o con strumenti interni prima di documentarlo e supportarlo pubblicamente. In questo modo possiamo apportare alcune modifiche per l'usabilità o la conformità agli standard senza preoccuparci di apportare un cambiamento temuto. Una volta che siamo soddisfatti del cambiamento, lo aggiungiamo alla nostra documentazione pubblica.
