Pratiche migliori per la versioning delle API RESTful: perché v1 è il numero 1
Chris McFadden
24 mag 2017
1 min read
Conclusioni principali
Il versioning delle API previene modifiche che romperebbero la compatibilità e preserva la fiducia tra fornitori di API e sviluppatori.
Le convenzioni di versioning chiare aiutano a evitare un mix caotico di versioni tra diversi endpoint.
Le API RESTful abbinate a semplici e espliciti URI di versione mantengono le integrazioni intuitive per gli sviluppatori.
I gruppi di governance garantiscono la coerenza tra i team, prevenendo modifiche accidentali che rompono la compatibilità.
Non tutte le modifiche richiedono una nuova versione — solo quelle che rompono le integrazioni esistenti.
Una buona documentazione è essenziale per evitare confusione e prevenire cambiamenti involontari che rompono la compatibilità.
Separare il deployment dal rilascio permette ai team di testare e perfezionare gli endpoint in sicurezza prima di annunciarli.
Quando le modifiche che rompono la compatibilità sono inevitabili, devono essere attentamente valutate e comunicate.
Q&A Highlights
Perché il versionamento API è importante?
Previene modifiche inaspettate che potrebbero interrompere gli sviluppi per i programmatori che integrano con la tua API, protegge la fiducia e garantisce stabilità a lungo termine per le applicazioni che dipendono da un comportamento coerente.
Quali sono le breaking changes in un API?
Qualsiasi modifica che cambia il comportamento delle integrazioni esistenti, come la rimozione di endpoint, l'alterazione dei valori predefiniti, l'aggiunta di campi richiesti o la modifica dei formati di risposta.
Perché SparkPost ha scelto REST come fondamento per il loro 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 bisogno di conoscenze specializzate dei sistemi sottostanti.
Come ha deciso SparkPost sul suo metodo di versioning?
Hanno valutato il versioning dell'header Accetta rispetto al versioning URI e hanno scelto il versioning URI perché è esplicito, semplice e più adatto agli sviluppatori.
Quale ruolo svolge un gruppo di governance API?
Stabilisce standard, garantisce coerenza e impedisce ai team di introdurre modifiche che confliggono con le convenzioni o infrangono la compatibilità.
Quali tipi di modifiche non sono considerati breaking?
Aggiunta di nuovi parametri opzionali, introduzione di nuovi endpoint, aggiunta di nuove chiavi nei payload JSON o modifica degli endpoint non pubblici — qualsiasi cosa che non interrompa il comportamento esistente.
Quali cambiamenti sono considerati breaking?
Aggiunta di parametri richiesti, rimozione di endpoint, modifica dei comportamenti predefiniti, alterazione della struttura di risposta o introduzione di campi JSON richiesti.
Perché la documentazione accurata è essenziale?
Impedisce modifiche involontarie che potrebbero rompere funzioni, 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 rilasciarli pubblicamente solo quando sono stabili, evitando un'esposizione prematura e potenzialmente problematica.
Cosa succede se si rende necessario un cambiamento radicale?
Deve essere raro, giustificato da chiari benefici, valutato attentamente per l'impatto sull'utente, e comunicato a fondo. Esempio: modificare la Suppression API solo dopo aver confermato un effetto minimo e aver fornito avviso.
Quindi, quanto può essere difficile gestire le versioni di un'API? La verità è che non è così difficile, ma ciò che è complicato è mantenere un po' di sanità mentale evitando di cadere inutilmente in un numero vertiginoso di versioni e sotto-versioni applicate a dozzine di endpoint API con compatibilità poco chiare.
I Cambiamenti Bruschi sono Male! API Versioning Buono!
Come chiunque abbia costruito o utilizzi regolarmente un API si rende conto prima o poi, le modifiche rompenti sono molto dannose e possono essere un serio difetto in un API altrimenti utile. Una modifica rompente è 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 e l'utente dell'API. Le modifiche rompenti richiedono che gli utenti siano avvisati in anticipo (con relative scuse) piuttosto che un cambiamento che appare semplicemente, come un nuovo e delizioso miglioramento. La via per evitare quella frustrazione è quella di versionare un API con la garanzia dal proprietario dell'API che non ci saranno modifiche sorprendenti introdotte all'interno di una singola versione.
Allora quanto può essere difficile versionare un API? La verità è che non lo è, ma ciò che è difficile è mantenere una certa sanità mentale evitando di cadere inutilmente in un numero vertiginoso di versioni e sotto-versioni applicate su dozzine di endpoint API con compatibilità poco chiare.
Abbiamo introdotto v1 dell'API tre anni fa e non ci siamo resi conto che sarebbe stato forte fino ad oggi. Quindi come abbiamo continuato a fornire il miglior API per la consegna di email per oltre due anni ma mantenere ancora la stessa versione API? Questa stabilità è cruciale per gli sviluppatori che costruiscono applicazioni con email APIs in cloud infrastructure, dove affidabilità e coerenza sono fondamentali. Sebbene ci siano molte opinioni diverse su come versionare i REST APIs, spero che la storia del nostro umile e potente v1 possa guidarti sulla strada per l'illuminazione della versionizzazione di API.
Come chiunque abbia costruito o utilizzi regolarmente un API si rende conto prima o poi, le modifiche rompenti sono molto dannose e possono essere un serio difetto in un API altrimenti utile. Una modifica rompente è 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 e l'utente dell'API. Le modifiche rompenti richiedono che gli utenti siano avvisati in anticipo (con relative scuse) piuttosto che un cambiamento che appare semplicemente, come un nuovo e delizioso miglioramento. La via per evitare quella frustrazione è quella di versionare un API con la garanzia dal proprietario dell'API che non ci saranno modifiche sorprendenti introdotte all'interno di una singola versione.
Allora quanto può essere difficile versionare un API? La verità è che non lo è, ma ciò che è difficile è mantenere una certa sanità mentale evitando di cadere inutilmente in un numero vertiginoso di versioni e sotto-versioni applicate su dozzine di endpoint API con compatibilità poco chiare.
Abbiamo introdotto v1 dell'API tre anni fa e non ci siamo resi conto che sarebbe stato forte fino ad oggi. Quindi come abbiamo continuato a fornire il miglior API per la consegna di email per oltre due anni ma mantenere ancora la stessa versione API? Questa stabilità è cruciale per gli sviluppatori che costruiscono applicazioni con email APIs in cloud infrastructure, dove affidabilità e coerenza sono fondamentali. Sebbene ci siano molte opinioni diverse su come versionare i REST APIs, spero che la storia del nostro umile e potente v1 possa guidarti sulla strada per l'illuminazione della versionizzazione di API.
Come chiunque abbia costruito o utilizzi regolarmente un API si rende conto prima o poi, le modifiche rompenti sono molto dannose e possono essere un serio difetto in un API altrimenti utile. Una modifica rompente è 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 e l'utente dell'API. Le modifiche rompenti richiedono che gli utenti siano avvisati in anticipo (con relative scuse) piuttosto che un cambiamento che appare semplicemente, come un nuovo e delizioso miglioramento. La via per evitare quella frustrazione è quella di versionare un API con la garanzia dal proprietario dell'API che non ci saranno modifiche sorprendenti introdotte all'interno di una singola versione.
Allora quanto può essere difficile versionare un API? La verità è che non lo è, ma ciò che è difficile è mantenere una certa sanità mentale evitando di cadere inutilmente in un numero vertiginoso di versioni e sotto-versioni applicate su dozzine di endpoint API con compatibilità poco chiare.
Abbiamo introdotto v1 dell'API tre anni fa e non ci siamo resi conto che sarebbe stato forte fino ad oggi. Quindi come abbiamo continuato a fornire il miglior API per la consegna di email per oltre due anni ma mantenere ancora la stessa versione API? Questa stabilità è cruciale per gli sviluppatori che costruiscono applicazioni con email APIs in cloud infrastructure, dove affidabilità e coerenza sono fondamentali. Sebbene ci siano molte opinioni diverse su come versionare i REST APIs, spero che la storia del nostro umile e potente v1 possa guidarti sulla strada per l'illuminazione della versionizzazione di API.
REST È Best
L'SparkPost API ha origine quando eravamo Message Systems, prima delle nostre avventure nel cloud. A quel tempo eravamo occupati a fare i preparativi finali per il lancio beta di Momentum 4. Questo era un aggiornamento importante 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, cosa più importante, una nuova web API per l'iniezione e la generazione di messaggi, gestione dei modelli e ottenimento delle metriche email. La nostra visione era un'architettura API first – dove anche l'interfaccia utente avrebbe interagito con gli endpoint API.
Una delle prime e migliori decisioni che prendemmo fu di adottare uno stile RESTful. Dai tardi anni 2000, il rappresentational state transfer (REST) basato su web API è lo standard de-facto delle API cloud. Usare HTTP e JSON rende facile per gli sviluppatori, indipendentemente dal linguaggio di programmazione che usano – PHP, Ruby e Java – integrarsi con la nostra API senza conoscere o preoccuparsi della nostra tecnologia sottostante. Tuttavia, costruire API native per il cloud su larga scala può presentare sfide infrastrutturali inaspettate, come i limiti di scalabilità DNS che abbiamo incontrato in AWS quando gestivamo traffico API ad alto volume.
Scegliere di utilizzare l'architettura RESTful è stato facile. Scegliere una convenzione di versionamento non è stato altrettanto semplice. Inizialmente abbiamo rinviato la questione del versionamento non versionando affatto il beta. Tuttavia, nel giro di pochi mesi il beta era nelle mani di alcuni clienti e abbiamo iniziato a sviluppare il nostro servizio cloud. Tempo di versionare. Abbiamo valutato due convenzioni di versionamento. La prima era inserire il versioning direttamente nell'URI e la seconda era usare un'intestazione Accept. La prima opzione è più esplicita e meno complicata, il che è più semplice per gli sviluppatori. Poiché amiamo gli sviluppatori, era la scelta logica.
L'SparkPost API ha origine quando eravamo Message Systems, prima delle nostre avventure nel cloud. A quel tempo eravamo occupati a fare i preparativi finali per il lancio beta di Momentum 4. Questo era un aggiornamento importante 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, cosa più importante, una nuova web API per l'iniezione e la generazione di messaggi, gestione dei modelli e ottenimento delle metriche email. La nostra visione era un'architettura API first – dove anche l'interfaccia utente avrebbe interagito con gli endpoint API.
Una delle prime e migliori decisioni che prendemmo fu di adottare uno stile RESTful. Dai tardi anni 2000, il rappresentational state transfer (REST) basato su web API è lo standard de-facto delle API cloud. Usare HTTP e JSON rende facile per gli sviluppatori, indipendentemente dal linguaggio di programmazione che usano – PHP, Ruby e Java – integrarsi con la nostra API senza conoscere o preoccuparsi della nostra tecnologia sottostante. Tuttavia, costruire API native per il cloud su larga scala può presentare sfide infrastrutturali inaspettate, come i limiti di scalabilità DNS che abbiamo incontrato in AWS quando gestivamo traffico API ad alto volume.
Scegliere di utilizzare l'architettura RESTful è stato facile. Scegliere una convenzione di versionamento non è stato altrettanto semplice. Inizialmente abbiamo rinviato la questione del versionamento non versionando affatto il beta. Tuttavia, nel giro di pochi mesi il beta era nelle mani di alcuni clienti e abbiamo iniziato a sviluppare il nostro servizio cloud. Tempo di versionare. Abbiamo valutato due convenzioni di versionamento. La prima era inserire il versioning direttamente nell'URI e la seconda era usare un'intestazione Accept. La prima opzione è più esplicita e meno complicata, il che è più semplice per gli sviluppatori. Poiché amiamo gli sviluppatori, era la scelta logica.
L'SparkPost API ha origine quando eravamo Message Systems, prima delle nostre avventure nel cloud. A quel tempo eravamo occupati a fare i preparativi finali per il lancio beta di Momentum 4. Questo era un aggiornamento importante 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, cosa più importante, una nuova web API per l'iniezione e la generazione di messaggi, gestione dei modelli e ottenimento delle metriche email. La nostra visione era un'architettura API first – dove anche l'interfaccia utente avrebbe interagito con gli endpoint API.
Una delle prime e migliori decisioni che prendemmo fu di adottare uno stile RESTful. Dai tardi anni 2000, il rappresentational state transfer (REST) basato su web API è lo standard de-facto delle API cloud. Usare HTTP e JSON rende facile per gli sviluppatori, indipendentemente dal linguaggio di programmazione che usano – PHP, Ruby e Java – integrarsi con la nostra API senza conoscere o preoccuparsi della nostra tecnologia sottostante. Tuttavia, costruire API native per il cloud su larga scala può presentare sfide infrastrutturali inaspettate, come i limiti di scalabilità DNS che abbiamo incontrato in AWS quando gestivamo traffico API ad alto volume.
Scegliere di utilizzare l'architettura RESTful è stato facile. Scegliere una convenzione di versionamento non è stato altrettanto semplice. Inizialmente abbiamo rinviato la questione del versionamento non versionando affatto il beta. Tuttavia, nel giro di pochi mesi il beta era nelle mani di alcuni clienti e abbiamo iniziato a sviluppare il nostro servizio cloud. Tempo di versionare. Abbiamo valutato due convenzioni di versionamento. La prima era inserire il versioning direttamente nell'URI e la seconda era usare un'intestazione Accept. La prima opzione è più esplicita e meno complicata, il che è più semplice per gli sviluppatori. Poiché amiamo gli sviluppatori, era la scelta logica.
API Governance
Con una convenzione di versionamento selezionata, avevamo più domande. Quando avremmo incrementato la versione? Cos'è una modifica dirompente? Avremmo fatto una nuova versione dell'intera API o solo di alcuni endpoint? In SparkPost, abbiamo più team che lavorano su diverse parti della nostra API. All'interno di questi team, le persone lavorano su endpoint diversi in momenti diversi. Pertanto, è molto importante che la nostra API sia coerente nell'uso delle convenzioni. Questo era qualcosa di più grande del solo versionamento.
Abbiamo istituito un gruppo di governance che include ingegneri che rappresentano ciascun team, un membro del team di Product Management e il nostro CTO. Questo gruppo è responsabile di stabilire, documentare e far rispettare le nostre convenzioni API su tutti i team. Un canale Slack di governance API è anche utile per vivaci dibattiti sull'argomento.
Il gruppo di governance ha identificato diversi modi in cui le modifiche possono essere introdotte nell'API che sono vantaggiose per l'utente e non costituiscono una modifica dirompente. Questi includono:
Una nuova risorsa o endpoint API
Un nuovo parametro opzionale
Una modifica a un endpoint API non pubblico
Una nuova chiave opzionale nel corpo POST JSON
Una nuova chiave restituita nel corpo della risposta JSON
Al contrario, una modifica dirompente includeva tutto ciò che potrebbe interrompere l'integrazione di un utente, come:
Un nuovo parametro richiesto
Una nuova chiave richiesta nei corpi POST
Rimozione di un endpoint esistente
Rimozione di un metodo di richiesta endpoint esistente
Un comportamento interno materialmente diverso di una chiamata API – come un cambiamento nel comportamento predefinito.
Con una convenzione di versionamento selezionata, avevamo più domande. Quando avremmo incrementato la versione? Cos'è una modifica dirompente? Avremmo fatto una nuova versione dell'intera API o solo di alcuni endpoint? In SparkPost, abbiamo più team che lavorano su diverse parti della nostra API. All'interno di questi team, le persone lavorano su endpoint diversi in momenti diversi. Pertanto, è molto importante che la nostra API sia coerente nell'uso delle convenzioni. Questo era qualcosa di più grande del solo versionamento.
Abbiamo istituito un gruppo di governance che include ingegneri che rappresentano ciascun team, un membro del team di Product Management e il nostro CTO. Questo gruppo è responsabile di stabilire, documentare e far rispettare le nostre convenzioni API su tutti i team. Un canale Slack di governance API è anche utile per vivaci dibattiti sull'argomento.
Il gruppo di governance ha identificato diversi modi in cui le modifiche possono essere introdotte nell'API che sono vantaggiose per l'utente e non costituiscono una modifica dirompente. Questi includono:
Una nuova risorsa o endpoint API
Un nuovo parametro opzionale
Una modifica a un endpoint API non pubblico
Una nuova chiave opzionale nel corpo POST JSON
Una nuova chiave restituita nel corpo della risposta JSON
Al contrario, una modifica dirompente includeva tutto ciò che potrebbe interrompere l'integrazione di un utente, come:
Un nuovo parametro richiesto
Una nuova chiave richiesta nei corpi POST
Rimozione di un endpoint esistente
Rimozione di un metodo di richiesta endpoint esistente
Un comportamento interno materialmente diverso di una chiamata API – come un cambiamento nel comportamento predefinito.
Con una convenzione di versionamento selezionata, avevamo più domande. Quando avremmo incrementato la versione? Cos'è una modifica dirompente? Avremmo fatto una nuova versione dell'intera API o solo di alcuni endpoint? In SparkPost, abbiamo più team che lavorano su diverse parti della nostra API. All'interno di questi team, le persone lavorano su endpoint diversi in momenti diversi. Pertanto, è molto importante che la nostra API sia coerente nell'uso delle convenzioni. Questo era qualcosa di più grande del solo versionamento.
Abbiamo istituito un gruppo di governance che include ingegneri che rappresentano ciascun team, un membro del team di Product Management e il nostro CTO. Questo gruppo è responsabile di stabilire, documentare e far rispettare le nostre convenzioni API su tutti i team. Un canale Slack di governance API è anche utile per vivaci dibattiti sull'argomento.
Il gruppo di governance ha identificato diversi modi in cui le modifiche possono essere introdotte nell'API che sono vantaggiose per l'utente e non costituiscono una modifica dirompente. Questi includono:
Una nuova risorsa o endpoint API
Un nuovo parametro opzionale
Una modifica a un endpoint API non pubblico
Una nuova chiave opzionale nel corpo POST JSON
Una nuova chiave restituita nel corpo della risposta JSON
Al contrario, una modifica dirompente includeva tutto ciò che potrebbe interrompere l'integrazione di un utente, come:
Un nuovo parametro richiesto
Una nuova chiave richiesta nei corpi POST
Rimozione di un endpoint esistente
Rimozione di un metodo di richiesta endpoint esistente
Un comportamento interno materialmente diverso di una chiamata API – come un cambiamento nel comportamento predefinito.
The Big 1.0
Mentre documentavamo e discutevamo queste convenzioni, siamo giunti anche alla conclusione che era nel migliore interesse di tutti (inclusi noi!) evitare di apportare modifiche che interrompessero l'API, poiché la gestione di più versioni aggiunge un bel po' di carico. Abbiamo deciso che c'erano alcune cose che dovevamo sistemare con la nostra API prima di impegnarci su "v1".
Inviando un semplice email richiedeva troppo sforzo. Per "mantenere le cose semplici", abbiamo aggiornato il corpo POST per garantire che siano accettati sia casi d'uso semplici che complessi. Il nuovo formato era anche più a prova di futuro. In secondo luogo, abbiamo affrontato un problema con l'endpoint Metrics. Questo endpoint utilizzava un parametro "group_by" che modificava il formato del corpo di risposta GET in modo tale che la prima chiave fosse il valore del parametro group by. Non sembrava molto RESTful, quindi abbiamo suddiviso ciascun group by in un endpoint separato. Infine, abbiamo verificato ogni endpoint e abbiamo apportato piccole modifiche qua e là per garantire che fossero conformi agli standard.
Mentre documentavamo e discutevamo queste convenzioni, siamo giunti anche alla conclusione che era nel migliore interesse di tutti (inclusi noi!) evitare di apportare modifiche che interrompessero l'API, poiché la gestione di più versioni aggiunge un bel po' di carico. Abbiamo deciso che c'erano alcune cose che dovevamo sistemare con la nostra API prima di impegnarci su "v1".
Inviando un semplice email richiedeva troppo sforzo. Per "mantenere le cose semplici", abbiamo aggiornato il corpo POST per garantire che siano accettati sia casi d'uso semplici che complessi. Il nuovo formato era anche più a prova di futuro. In secondo luogo, abbiamo affrontato un problema con l'endpoint Metrics. Questo endpoint utilizzava un parametro "group_by" che modificava il formato del corpo di risposta GET in modo tale che la prima chiave fosse il valore del parametro group by. Non sembrava molto RESTful, quindi abbiamo suddiviso ciascun group by in un endpoint separato. Infine, abbiamo verificato ogni endpoint e abbiamo apportato piccole modifiche qua e là per garantire che fossero conformi agli standard.
Mentre documentavamo e discutevamo queste convenzioni, siamo giunti anche alla conclusione che era nel migliore interesse di tutti (inclusi noi!) evitare di apportare modifiche che interrompessero l'API, poiché la gestione di più versioni aggiunge un bel po' di carico. Abbiamo deciso che c'erano alcune cose che dovevamo sistemare con la nostra API prima di impegnarci su "v1".
Inviando un semplice email richiedeva troppo sforzo. Per "mantenere le cose semplici", abbiamo aggiornato il corpo POST per garantire che siano accettati sia casi d'uso semplici che complessi. Il nuovo formato era anche più a prova di futuro. In secondo luogo, abbiamo affrontato un problema con l'endpoint Metrics. Questo endpoint utilizzava un parametro "group_by" che modificava il formato del corpo di risposta GET in modo tale che la prima chiave fosse il valore del parametro group by. Non sembrava molto RESTful, quindi abbiamo suddiviso ciascun group by in un endpoint separato. Infine, abbiamo verificato ogni endpoint e abbiamo apportato piccole modifiche qua e là per garantire che fossero conformi agli standard.
Documentazione Accurata
È importante avere documentazione API accurata e utilizzabile per evitare modifiche che interrompono il funzionamento, siano esse deliberate o involontarie. Abbiamo deciso di utilizzare un approccio semplice alla documentazione API sfruttando un linguaggio Markdown chiamato API Blueprint e gestire i nostri documenti su Github. La nostra comunità contribuisce e migliora questi documenti open source. Manteniamo anche un set di documenti non pubblico su Github per API e endpoint interni.
Inizialmente, abbiamo pubblicato i nostri documenti su Apiary, un ottimo strumento per prototipare e pubblicare documenti API. Tuttavia, l'integrazione di Apiary nel nostro sito web non funziona sui dispositivi mobili, quindi ora usiamo Jekyll per generare documenti statici. I nostri ultimi SparkPost API docs ora si caricano rapidamente e funzionano bene sui dispositivi mobili, il che è importante per gli sviluppatori che non sono sempre alla scrivania.
È importante avere documentazione API accurata e utilizzabile per evitare modifiche che interrompono il funzionamento, siano esse deliberate o involontarie. Abbiamo deciso di utilizzare un approccio semplice alla documentazione API sfruttando un linguaggio Markdown chiamato API Blueprint e gestire i nostri documenti su Github. La nostra comunità contribuisce e migliora questi documenti open source. Manteniamo anche un set di documenti non pubblico su Github per API e endpoint interni.
Inizialmente, abbiamo pubblicato i nostri documenti su Apiary, un ottimo strumento per prototipare e pubblicare documenti API. Tuttavia, l'integrazione di Apiary nel nostro sito web non funziona sui dispositivi mobili, quindi ora usiamo Jekyll per generare documenti statici. I nostri ultimi SparkPost API docs ora si caricano rapidamente e funzionano bene sui dispositivi mobili, il che è importante per gli sviluppatori che non sono sempre alla scrivania.
È importante avere documentazione API accurata e utilizzabile per evitare modifiche che interrompono il funzionamento, siano esse deliberate o involontarie. Abbiamo deciso di utilizzare un approccio semplice alla documentazione API sfruttando un linguaggio Markdown chiamato API Blueprint e gestire i nostri documenti su Github. La nostra comunità contribuisce e migliora questi documenti open source. Manteniamo anche un set di documenti non pubblico su Github per API e endpoint interni.
Inizialmente, abbiamo pubblicato i nostri documenti su Apiary, un ottimo strumento per prototipare e pubblicare documenti API. Tuttavia, l'integrazione di Apiary nel nostro sito web non funziona sui dispositivi mobili, quindi ora usiamo Jekyll per generare documenti statici. I nostri ultimi SparkPost API docs ora si caricano rapidamente e funzionano bene sui dispositivi mobili, il che è importante per gli sviluppatori che non sono sempre alla scrivania.
Separare Deployment da Release
Abbiamo imparato presto il prezioso trucco di separare un deployment da un rilascio. In questo modo è possibile distribuire frequentemente modifiche quando sono pronte attraverso consegna e distribuzione continue, ma non le annunciamo sempre pubblicamente o le documentiamo allo stesso tempo. Non è raro per noi distribuire un nuovo endpoint API o un miglioramento a un endpoint API esistente e utilizzarlo dall'interno dell'interfaccia utente o con strumenti interni prima di documentarlo pubblicamente e supportarlo. In questo modo possiamo apportare alcune modifiche per la facilità d'uso o la conformità agli standard senza preoccuparci di creare un temuto cambiamento che rompa. 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 modifiche quando sono pronte attraverso consegna e distribuzione continue, ma non le annunciamo sempre pubblicamente o le documentiamo allo stesso tempo. Non è raro per noi distribuire un nuovo endpoint API o un miglioramento a un endpoint API esistente e utilizzarlo dall'interno dell'interfaccia utente o con strumenti interni prima di documentarlo pubblicamente e supportarlo. In questo modo possiamo apportare alcune modifiche per la facilità d'uso o la conformità agli standard senza preoccuparci di creare un temuto cambiamento che rompa. 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 modifiche quando sono pronte attraverso consegna e distribuzione continue, ma non le annunciamo sempre pubblicamente o le documentiamo allo stesso tempo. Non è raro per noi distribuire un nuovo endpoint API o un miglioramento a un endpoint API esistente e utilizzarlo dall'interno dell'interfaccia utente o con strumenti interni prima di documentarlo pubblicamente e supportarlo. In questo modo possiamo apportare alcune modifiche per la facilità d'uso o la conformità agli standard senza preoccuparci di creare un temuto cambiamento che rompa. Una volta che siamo soddisfatti del cambiamento, lo aggiungiamo alla nostra documentazione pubblica.
Accidenti!
È giusto ammettere che ci sono stati momenti in cui non siamo stati fedeli ai nostri ideali di “no breaking changes” e vale la pena imparare da questi. In un'occasione abbiamo deciso che sarebbe stato meglio per gli utenti se una determinata proprietà fosse predefinita su true invece che su false. Dopo aver implementato la modifica, abbiamo ricevuto diverse lamentele dagli 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 breaking changes come risultato di correzioni di bug. Tuttavia, abbiamo deciso di lasciare queste idiosincrasie piuttosto che rischiare di compromettere le integrazioni dei clienti per il bene della coerenza.
Ci sono rari casi in cui abbiamo preso la seria decisione di apportare una modifica che rompe qualcosa, come deprecare una risorsa o un metodo API, nell'interesse della comunità utente più ampia e solo dopo aver confermato che c'è poco o nessun impatto sugli utenti. Ad esempio, abbiamo deliberatamente scelto di modificare il comportamento di risposta della Suppression API, ma solo dopo aver attentamente valutato i benefici e gli impatti per la comunità e comunicato attentamente la modifica ai nostri utenti. Tuttavia, non introduceremmo mai una modifica che abbia una remota possibilità di influenzare direttamente l'invio di un’email di produzione dell’utente.
È giusto ammettere che ci sono stati momenti in cui non siamo stati fedeli ai nostri ideali di “no breaking changes” e vale la pena imparare da questi. In un'occasione abbiamo deciso che sarebbe stato meglio per gli utenti se una determinata proprietà fosse predefinita su true invece che su false. Dopo aver implementato la modifica, abbiamo ricevuto diverse lamentele dagli 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 breaking changes come risultato di correzioni di bug. Tuttavia, abbiamo deciso di lasciare queste idiosincrasie piuttosto che rischiare di compromettere le integrazioni dei clienti per il bene della coerenza.
Ci sono rari casi in cui abbiamo preso la seria decisione di apportare una modifica che rompe qualcosa, come deprecare una risorsa o un metodo API, nell'interesse della comunità utente più ampia e solo dopo aver confermato che c'è poco o nessun impatto sugli utenti. Ad esempio, abbiamo deliberatamente scelto di modificare il comportamento di risposta della Suppression API, ma solo dopo aver attentamente valutato i benefici e gli impatti per la comunità e comunicato attentamente la modifica ai nostri utenti. Tuttavia, non introduceremmo mai una modifica che abbia una remota possibilità di influenzare direttamente l'invio di un’email di produzione dell’utente.
È giusto ammettere che ci sono stati momenti in cui non siamo stati fedeli ai nostri ideali di “no breaking changes” e vale la pena imparare da questi. In un'occasione abbiamo deciso che sarebbe stato meglio per gli utenti se una determinata proprietà fosse predefinita su true invece che su false. Dopo aver implementato la modifica, abbiamo ricevuto diverse lamentele dagli 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 breaking changes come risultato di correzioni di bug. Tuttavia, abbiamo deciso di lasciare queste idiosincrasie piuttosto che rischiare di compromettere le integrazioni dei clienti per il bene della coerenza.
Ci sono rari casi in cui abbiamo preso la seria decisione di apportare una modifica che rompe qualcosa, come deprecare una risorsa o un metodo API, nell'interesse della comunità utente più ampia e solo dopo aver confermato che c'è poco o nessun impatto sugli utenti. Ad esempio, abbiamo deliberatamente scelto di modificare il comportamento di risposta della Suppression API, ma solo dopo aver attentamente valutato i benefici e gli impatti per la comunità e comunicato attentamente la modifica ai nostri utenti. Tuttavia, non introduceremmo mai una modifica che abbia una remota possibilità di influenzare direttamente l'invio di un’email di produzione dell’utente.
