RESTful API Versievormings Best Practices: Waarom v1 de #1 is
Chris McFadden
24 mei 2017
1 min read
Belangrijkste punten
API-versiebeheer voorkomt verstorende wijzigingen en behoudt het vertrouwen tussen API-providers en ontwikkelaars.
Duidelijke versieconventies helpen een chaotische mix van versies over eindpunten te voorkomen.
RESTful APIs gekoppeld met eenvoudige, expliciete versie-URI's houden integraties intuïtief voor ontwikkelaars.
Governancegroepen zorgen voor consistentie tussen teams, waardoor toevallige verstorende wijzigingen worden voorkomen.
Niet alle wijzigingen vereisen een nieuwe versie — alleen diegene die bestaande integraties verbreken.
Goede documentatie is essentieel om verwarring te voorkomen en onbedoelde verstorende wijzigingen te voorkomen.
Het scheiden van implementatie en release stelt teams in staat om eindpunten veilig te testen en verfijnen voordat ze worden aangekondigd.
Wanneer verstorende wijzigingen onvermijdelijk zijn, moeten ze zorgvuldig worden geëvalueerd en gecommuniceerd.
Q&A Hoogtepunten
Waarom is API-versiebeheer belangrijk?
Het voorkomt onverwachte wijzigingen die voor ontwikkelaars breuken kunnen veroorzaken bij het integreren met je API, beschermt vertrouwen en zorgt voor langdurige stabiliteit voor applicaties die afhankelijk zijn van consistent gedrag.
Wat zijn breaking changes in een API?
Elke wijziging die verandert hoe bestaande integraties zich gedragen — zoals het verwijderen van eindpunten, het veranderen van standaarden, het toevoegen van vereiste velden, of het wijzigen van responsformaten.
Waarom heeft SparkPost REST gekozen als de basis voor hun API?
Het gebruik van HTTP en JSON door REST maakt het gemakkelijk voor ontwikkelaars in verschillende talen (PHP, Ruby, Java, enz.) om te integreren zonder gespecialiseerde kennis van onderliggende systemen nodig te hebben.
Hoe heeft SparkPost besloten over zijn versionering methode?
Zij evalueerden Accept-header versiebeheer versus URI versiebeheer en kozen voor URI versiebeheer omdat het expliciet, eenvoudig en meer ontwikkelaarsvriendelijk is.
Welke rol speelt een API governance groep?
Het stelt normen vast, handhaaft consistentie en voorkomt dat teams wijzigingen doorvoeren die in strijd zijn met conventies of de compatibiliteit verbreken.
Welke soorten wijzigingen worden niet als breaking beschouwd?
Het toevoegen van nieuwe optionele parameters, het introduceren van nieuwe eindpunten, het toevoegen van nieuwe sleutels in JSON-payloads, of het wijzigen van niet-openbare eindpunten — alles wat het bestaande gedrag niet verstoort.
Welke wijzigingen worden als breaking beschouwd?
Vereiste parameters toevoegen, endpoints verwijderen, standaardgedragingen veranderen, de structuur van de respons wijzigen of vereiste JSON-velden toevoegen.
Waarom is accurate documentatie essentieel?
Het voorkomt onbedoelde breaking changes, helpt ontwikkelaars gedrag te begrijpen en zorgt ervoor dat teams de API betrouwbaar bijwerken. SparkPost gebruikte Markdown (API Blueprint) en GitHub om helderheid en openheid te behouden.
Wat is het voordeel van het scheiden van deployment van release?
Teams kunnen continu nieuwe endpoints of verbeteringen intern implementeren, ze testen in echte workflows, gedrag verfijnen, en pas openbaar vrijgeven als ze stabiel zijn — voortijdige en mogelijk brekende blootstelling vermijden.
Wat gebeurt er als een breaking change noodzakelijk wordt?
Het moet zeldzaam zijn, gerechtvaardigd door duidelijke voordelen, zorgvuldig geëvalueerd op gebruikersimpact en grondig gecommuniceerd. Voorbeeld: het aanpassen van de Suppression API alleen na bevestiging van minimaal effect en het geven van een kennisgeving.
Dus hoe moeilijk kan het zijn om een API te versieën? De waarheid is dat het niet moeilijk is, maar wat wel moeilijk is, is het behouden van enige gezond verstand door niet onnodig te verzanden in een duizelingwekkend aantal versies en subversies die worden toegepast op tientallen API-eindpunten met onduidelijke compatibiliteit.
Dus hoe moeilijk kan het zijn om een API te versieën? De waarheid is dat het niet moeilijk is, maar wat wel moeilijk is, is het behouden van enige gezond verstand door niet onnodig te verzanden in een duizelingwekkend aantal versies en subversies die worden toegepast op tientallen API-eindpunten met onduidelijke compatibiliteit.
Dus hoe moeilijk kan het zijn om een API te versieën? De waarheid is dat het niet moeilijk is, maar wat wel moeilijk is, is het behouden van enige gezond verstand door niet onnodig te verzanden in een duizelingwekkend aantal versies en subversies die worden toegepast op tientallen API-eindpunten met onduidelijke compatibiliteit.
Doh!
Het is alleen eerlijk om toe te geven dat er momenten zijn geweest waarop we onze “geen breaking changes”-idealen niet hebben waargemaakt, en het is de moeite waard om hiervan te leren. Op een gegeven moment besloten we dat het beter zou zijn voor gebruikers als een bepaalde instelling standaard op true stond in plaats van false. Nadat we de wijziging hadden doorgevoerd, ontvingen we verschillende klachten van gebruikers omdat het gedrag onverwachts was veranderd. We draaiden de wijziging terug en voegden een accountniveau-instelling toe – een veel gebruiksvriendelijkere benadering, dat is zeker.
Soms worden we verleid om breaking changes door te voeren als gevolg van bugfixes. Echter, we besloten deze eigenaardigheden met rust te laten in plaats van het riskeren van het verbreken van klantintegraties voor het behoud van consistentie.
Er zijn zeldzame gevallen waarin we de serieuze beslissing namen om een breaking change door te voeren – zoals het afschaffen van een API-resource of -methode – in het belang van de bredere gebruikersgemeenschap en pas na bevestiging dat er weinig tot geen impact is op gebruikers. Bijvoorbeeld, we maakten bewust de keuze om het reactiegedrag van de Suppression API te wijzigen, maar alleen na zorgvuldig afwegen van de voordelen en nadelen voor de gemeenschap en het zorgvuldig communiceren van de wijziging naar onze gebruikers. Echter, we zouden nooit een wijziging introduceren die zelfs maar een geringe mogelijkheid heeft om direct invloed te hebben op het verzenden van een productie-e-mail van een gebruiker.
Het is alleen eerlijk om toe te geven dat er momenten zijn geweest waarop we onze “geen breaking changes”-idealen niet hebben waargemaakt, en het is de moeite waard om hiervan te leren. Op een gegeven moment besloten we dat het beter zou zijn voor gebruikers als een bepaalde instelling standaard op true stond in plaats van false. Nadat we de wijziging hadden doorgevoerd, ontvingen we verschillende klachten van gebruikers omdat het gedrag onverwachts was veranderd. We draaiden de wijziging terug en voegden een accountniveau-instelling toe – een veel gebruiksvriendelijkere benadering, dat is zeker.
Soms worden we verleid om breaking changes door te voeren als gevolg van bugfixes. Echter, we besloten deze eigenaardigheden met rust te laten in plaats van het riskeren van het verbreken van klantintegraties voor het behoud van consistentie.
Er zijn zeldzame gevallen waarin we de serieuze beslissing namen om een breaking change door te voeren – zoals het afschaffen van een API-resource of -methode – in het belang van de bredere gebruikersgemeenschap en pas na bevestiging dat er weinig tot geen impact is op gebruikers. Bijvoorbeeld, we maakten bewust de keuze om het reactiegedrag van de Suppression API te wijzigen, maar alleen na zorgvuldig afwegen van de voordelen en nadelen voor de gemeenschap en het zorgvuldig communiceren van de wijziging naar onze gebruikers. Echter, we zouden nooit een wijziging introduceren die zelfs maar een geringe mogelijkheid heeft om direct invloed te hebben op het verzenden van een productie-e-mail van een gebruiker.
Het is alleen eerlijk om toe te geven dat er momenten zijn geweest waarop we onze “geen breaking changes”-idealen niet hebben waargemaakt, en het is de moeite waard om hiervan te leren. Op een gegeven moment besloten we dat het beter zou zijn voor gebruikers als een bepaalde instelling standaard op true stond in plaats van false. Nadat we de wijziging hadden doorgevoerd, ontvingen we verschillende klachten van gebruikers omdat het gedrag onverwachts was veranderd. We draaiden de wijziging terug en voegden een accountniveau-instelling toe – een veel gebruiksvriendelijkere benadering, dat is zeker.
Soms worden we verleid om breaking changes door te voeren als gevolg van bugfixes. Echter, we besloten deze eigenaardigheden met rust te laten in plaats van het riskeren van het verbreken van klantintegraties voor het behoud van consistentie.
Er zijn zeldzame gevallen waarin we de serieuze beslissing namen om een breaking change door te voeren – zoals het afschaffen van een API-resource of -methode – in het belang van de bredere gebruikersgemeenschap en pas na bevestiging dat er weinig tot geen impact is op gebruikers. Bijvoorbeeld, we maakten bewust de keuze om het reactiegedrag van de Suppression API te wijzigen, maar alleen na zorgvuldig afwegen van de voordelen en nadelen voor de gemeenschap en het zorgvuldig communiceren van de wijziging naar onze gebruikers. Echter, we zouden nooit een wijziging introduceren die zelfs maar een geringe mogelijkheid heeft om direct invloed te hebben op het verzenden van een productie-e-mail van een gebruiker.
Breaking Changes Slecht! API Versioning Goed!
Zoals iedereen die een API heeft gebouwd of regelmatig gebruikt, vroeg of laat beseft, zijn breaking changes zeer slecht en kunnen ze een zeer ernstige smet zijn op een anders nuttige API. Een breaking change is een wijziging in het gedrag van een API die de integratie van een gebruiker kan breken en kan resulteren in veel frustratie en verlies van vertrouwen tussen de API-provider en gebruiker. Breaking changes vereisen dat gebruikers vooraf op de hoogte worden gesteld (met bijbehorende mea culpa's) in plaats van een wijziging die gewoon verschijnt, zoals een geweldig nieuwe functie. De manier om die frustratie te voorkomen is door een versie van een API aan te geven met garanties van de API-eigenaar dat er binnen een enkele versie geen verrassende wijzigingen worden geïntroduceerd.
Dus hoe moeilijk kan het zijn om een API te versienummeren? De waarheid is dat het niet moeilijk is, maar wat wel moeilijk is, is enige helderheid te behouden door niet zinloos te vervallen in een duizelingwekkend aantal versies en subversies, toegepast op tientallen API-eindpunten met onduidelijke compatibiliteiten.
We hebben drie jaar geleden v1 van de API geïntroduceerd en hadden niet verwacht dat het tot op de dag van vandaag sterk zou blijven. Dus hoe zijn we erin geslaagd om al meer dan twee jaar de beste e-mailbezorgings-API te bieden, maar nog steeds dezelfde API-versie te behouden? Deze stabiliteit is cruciaal voor ontwikkelaars die applicaties bouwen met e-mail-API's in cloudinfrastructuur, waar betrouwbaarheid en consistentie van het grootste belang zijn. Hoewel er veel verschillende meningen zijn over hoe REST-API's te versienummeren, hoop ik dat het verhaal van onze bescheiden maar krachtige v1 je kan begeleiden op weg naar verlichting in API-versienummering.
Zoals iedereen die een API heeft gebouwd of regelmatig gebruikt, vroeg of laat beseft, zijn breaking changes zeer slecht en kunnen ze een zeer ernstige smet zijn op een anders nuttige API. Een breaking change is een wijziging in het gedrag van een API die de integratie van een gebruiker kan breken en kan resulteren in veel frustratie en verlies van vertrouwen tussen de API-provider en gebruiker. Breaking changes vereisen dat gebruikers vooraf op de hoogte worden gesteld (met bijbehorende mea culpa's) in plaats van een wijziging die gewoon verschijnt, zoals een geweldig nieuwe functie. De manier om die frustratie te voorkomen is door een versie van een API aan te geven met garanties van de API-eigenaar dat er binnen een enkele versie geen verrassende wijzigingen worden geïntroduceerd.
Dus hoe moeilijk kan het zijn om een API te versienummeren? De waarheid is dat het niet moeilijk is, maar wat wel moeilijk is, is enige helderheid te behouden door niet zinloos te vervallen in een duizelingwekkend aantal versies en subversies, toegepast op tientallen API-eindpunten met onduidelijke compatibiliteiten.
We hebben drie jaar geleden v1 van de API geïntroduceerd en hadden niet verwacht dat het tot op de dag van vandaag sterk zou blijven. Dus hoe zijn we erin geslaagd om al meer dan twee jaar de beste e-mailbezorgings-API te bieden, maar nog steeds dezelfde API-versie te behouden? Deze stabiliteit is cruciaal voor ontwikkelaars die applicaties bouwen met e-mail-API's in cloudinfrastructuur, waar betrouwbaarheid en consistentie van het grootste belang zijn. Hoewel er veel verschillende meningen zijn over hoe REST-API's te versienummeren, hoop ik dat het verhaal van onze bescheiden maar krachtige v1 je kan begeleiden op weg naar verlichting in API-versienummering.
Zoals iedereen die een API heeft gebouwd of regelmatig gebruikt, vroeg of laat beseft, zijn breaking changes zeer slecht en kunnen ze een zeer ernstige smet zijn op een anders nuttige API. Een breaking change is een wijziging in het gedrag van een API die de integratie van een gebruiker kan breken en kan resulteren in veel frustratie en verlies van vertrouwen tussen de API-provider en gebruiker. Breaking changes vereisen dat gebruikers vooraf op de hoogte worden gesteld (met bijbehorende mea culpa's) in plaats van een wijziging die gewoon verschijnt, zoals een geweldig nieuwe functie. De manier om die frustratie te voorkomen is door een versie van een API aan te geven met garanties van de API-eigenaar dat er binnen een enkele versie geen verrassende wijzigingen worden geïntroduceerd.
Dus hoe moeilijk kan het zijn om een API te versienummeren? De waarheid is dat het niet moeilijk is, maar wat wel moeilijk is, is enige helderheid te behouden door niet zinloos te vervallen in een duizelingwekkend aantal versies en subversies, toegepast op tientallen API-eindpunten met onduidelijke compatibiliteiten.
We hebben drie jaar geleden v1 van de API geïntroduceerd en hadden niet verwacht dat het tot op de dag van vandaag sterk zou blijven. Dus hoe zijn we erin geslaagd om al meer dan twee jaar de beste e-mailbezorgings-API te bieden, maar nog steeds dezelfde API-versie te behouden? Deze stabiliteit is cruciaal voor ontwikkelaars die applicaties bouwen met e-mail-API's in cloudinfrastructuur, waar betrouwbaarheid en consistentie van het grootste belang zijn. Hoewel er veel verschillende meningen zijn over hoe REST-API's te versienummeren, hoop ik dat het verhaal van onze bescheiden maar krachtige v1 je kan begeleiden op weg naar verlichting in API-versienummering.
REST Is Best
De SparkPost API stamt uit de tijd dat we bekend stonden als Message Systems, voordat we onze avonturen in de cloud begonnen. Destijds waren we druk bezig met de laatste voorbereidingen voor de bèta-lancering van Momentum 4. Dit was een grote upgrade van versie 3.x, onze marktleidende on-premise MTA. Momentum 4 bevatte een geheel nieuwe UI, real-time analytics, en vooral een nieuwe web API voor berichteninjectie en -generatie, het beheren van sjablonen en het verkrijgen van e-mailstatistieken. Onze visie was een API-eerst architectuur - waarin zelfs de UI zou communiceren met API-eindpunten.
Een van de vroegste en beste beslissingen die we namen, was het aannemen van een RESTful stijl. Sinds het eind van de jaren 2000 zijn representational state transfer (REST) gebaseerde web API's de de-facto standaard van cloud API's. Het gebruik van HTTP en JSON maakt het gemakkelijk voor ontwikkelaars, ongeacht welke programmeertaal ze gebruiken – PHP, Ruby en Java – om zich te integreren met onze API zonder kennis of zorg over onze onderliggende technologie. Echter, het bouwen van cloud-native API's op schaal kan onverwachte infrastructurele uitdagingen met zich meebrengen, zoals de DNS schaalbaarheidslimieten die we tegenkwamen in AWS bij het verwerken van grote hoeveelheden API-verkeer.
Kiezen voor de RESTful architectuur was gemakkelijk. Het kiezen van een versiebeheerconventie was niet zo eenvoudig. Aanvankelijk stortten we ons niet op de kwestie van versiebeheer door de bèta helemaal niet te versioneren. Echter, binnen enkele maanden was de bèta in handen van een paar klanten en begonnen we onze clouddienst uit te bouwen. Tijd om te versioneren. We evalueerden twee versiebeheerconventies.
Versioneringsaanpak | Hoe het werkt | Afweging |
|---|---|---|
URI versionering | Versie opgenomen in eindpuntpad | Expliciet en gemakkelijk te begrijpen |
Accept header versionering | Versie doorgegeven via HTTP-header | Minder zichtbaar, complexer voor ontwikkelaars |
De eerste was om de versionering rechtstreeks in de URI te plaatsen en de tweede was om een Accept-header te gebruiken. De eerste optie is duidelijker en minder ingewikkeld, wat makkelijker is voor ontwikkelaars. Omdat we dol zijn op ontwikkelaars, was dit de logische keuze.
De SparkPost API stamt uit de tijd dat we bekend stonden als Message Systems, voordat we onze avonturen in de cloud begonnen. Destijds waren we druk bezig met de laatste voorbereidingen voor de bèta-lancering van Momentum 4. Dit was een grote upgrade van versie 3.x, onze marktleidende on-premise MTA. Momentum 4 bevatte een geheel nieuwe UI, real-time analytics, en vooral een nieuwe web API voor berichteninjectie en -generatie, het beheren van sjablonen en het verkrijgen van e-mailstatistieken. Onze visie was een API-eerst architectuur - waarin zelfs de UI zou communiceren met API-eindpunten.
Een van de vroegste en beste beslissingen die we namen, was het aannemen van een RESTful stijl. Sinds het eind van de jaren 2000 zijn representational state transfer (REST) gebaseerde web API's de de-facto standaard van cloud API's. Het gebruik van HTTP en JSON maakt het gemakkelijk voor ontwikkelaars, ongeacht welke programmeertaal ze gebruiken – PHP, Ruby en Java – om zich te integreren met onze API zonder kennis of zorg over onze onderliggende technologie. Echter, het bouwen van cloud-native API's op schaal kan onverwachte infrastructurele uitdagingen met zich meebrengen, zoals de DNS schaalbaarheidslimieten die we tegenkwamen in AWS bij het verwerken van grote hoeveelheden API-verkeer.
Kiezen voor de RESTful architectuur was gemakkelijk. Het kiezen van een versiebeheerconventie was niet zo eenvoudig. Aanvankelijk stortten we ons niet op de kwestie van versiebeheer door de bèta helemaal niet te versioneren. Echter, binnen enkele maanden was de bèta in handen van een paar klanten en begonnen we onze clouddienst uit te bouwen. Tijd om te versioneren. We evalueerden twee versiebeheerconventies.
Versioneringsaanpak | Hoe het werkt | Afweging |
|---|---|---|
URI versionering | Versie opgenomen in eindpuntpad | Expliciet en gemakkelijk te begrijpen |
Accept header versionering | Versie doorgegeven via HTTP-header | Minder zichtbaar, complexer voor ontwikkelaars |
De eerste was om de versionering rechtstreeks in de URI te plaatsen en de tweede was om een Accept-header te gebruiken. De eerste optie is duidelijker en minder ingewikkeld, wat makkelijker is voor ontwikkelaars. Omdat we dol zijn op ontwikkelaars, was dit de logische keuze.
De SparkPost API stamt uit de tijd dat we bekend stonden als Message Systems, voordat we onze avonturen in de cloud begonnen. Destijds waren we druk bezig met de laatste voorbereidingen voor de bèta-lancering van Momentum 4. Dit was een grote upgrade van versie 3.x, onze marktleidende on-premise MTA. Momentum 4 bevatte een geheel nieuwe UI, real-time analytics, en vooral een nieuwe web API voor berichteninjectie en -generatie, het beheren van sjablonen en het verkrijgen van e-mailstatistieken. Onze visie was een API-eerst architectuur - waarin zelfs de UI zou communiceren met API-eindpunten.
Een van de vroegste en beste beslissingen die we namen, was het aannemen van een RESTful stijl. Sinds het eind van de jaren 2000 zijn representational state transfer (REST) gebaseerde web API's de de-facto standaard van cloud API's. Het gebruik van HTTP en JSON maakt het gemakkelijk voor ontwikkelaars, ongeacht welke programmeertaal ze gebruiken – PHP, Ruby en Java – om zich te integreren met onze API zonder kennis of zorg over onze onderliggende technologie. Echter, het bouwen van cloud-native API's op schaal kan onverwachte infrastructurele uitdagingen met zich meebrengen, zoals de DNS schaalbaarheidslimieten die we tegenkwamen in AWS bij het verwerken van grote hoeveelheden API-verkeer.
Kiezen voor de RESTful architectuur was gemakkelijk. Het kiezen van een versiebeheerconventie was niet zo eenvoudig. Aanvankelijk stortten we ons niet op de kwestie van versiebeheer door de bèta helemaal niet te versioneren. Echter, binnen enkele maanden was de bèta in handen van een paar klanten en begonnen we onze clouddienst uit te bouwen. Tijd om te versioneren. We evalueerden twee versiebeheerconventies.
Versioneringsaanpak | Hoe het werkt | Afweging |
|---|---|---|
URI versionering | Versie opgenomen in eindpuntpad | Expliciet en gemakkelijk te begrijpen |
Accept header versionering | Versie doorgegeven via HTTP-header | Minder zichtbaar, complexer voor ontwikkelaars |
De eerste was om de versionering rechtstreeks in de URI te plaatsen en de tweede was om een Accept-header te gebruiken. De eerste optie is duidelijker en minder ingewikkeld, wat makkelijker is voor ontwikkelaars. Omdat we dol zijn op ontwikkelaars, was dit de logische keuze.
API Governance
Met een versie-conventie geselecteerd hadden we meer vragen. Wanneer zouden we de versie verhogen? Wat is een brekende wijziging? Zouden we de hele API opnieuw versienummeren of slechts bepaalde endpoints? Bij SparkPost werken we met meerdere teams aan verschillende delen van onze API. Binnen die teams werken mensen op verschillende momenten aan verschillende endpoints. Daarom is het erg belangrijk dat onze API consistent is in het gebruik van conventies. Dit was groter dan alleen versiebeheer.
We hebben een bestuursgroep opgericht met onder meer ingenieurs die elk team vertegenwoordigen, een lid van het Product Management-team en onze CTO. Deze groep is verantwoordelijk voor het opstellen, documenteren en handhaven van onze API-conventies binnen alle teams. Een API-governance Slack-kanaal is ook handig voor levendige debatten over het onderwerp.
De bestuursgroep identificeerde verschillende manieren waarop wijzigingen aan de API kunnen worden geïntroduceerd die voordelig zijn voor de gebruiker en geen brekende wijzigingen vormen.
Wijzigingstype | Brekend beschouwd? | Reden |
|---|---|---|
Nieuwe bron of endpoint | Nee | Heeft geen invloed op bestaande integraties |
Nieuwe optionele parameter | Nee | Bestaande verzoeken blijven geldig |
Nieuwe optionele JSON-sleutel | Nee | Clients kunnen het veilig negeren |
Nieuw responsveld | Nee | Achterwaarts compatibel voor gebruikers |
Nieuwe vereiste parameter | Ja | Breekt bestaande verzoeken |
Nieuwe vereiste POST-sleutel | Ja | Maakt bestaande payloads ongeldig |
Verwijderen van een endpoint | Ja | Bestaande integraties falen |
Veranderen van standaardgedrag | Ja | Wijzigt verwachte uitkomsten |
Deze omvatten:
Een nieuwe bron of API-endpoint
Een nieuwe optionele parameter
Een wijziging aan een niet-openbaar API-endpoint
Een nieuwe optionele sleutel in de JSON POST-body
Een nieuwe sleutel die in de JSON-responsetcode wordt geretourneerd
Daarentegen omvatte een brekende wijziging alles wat de integratie van een gebruiker zou kunnen breken, zoals:
Een nieuwe vereiste parameter
Een nieuwe vereiste sleutel in POST-bodies
Verwijderen van een bestaand endpoint
Verwijderen van een bestaande endpoint-aanroepmethode
Een materieel ander intern gedrag van een API-aanroep – zoals een wijziging in het standaardgedrag.
Met een versie-conventie geselecteerd hadden we meer vragen. Wanneer zouden we de versie verhogen? Wat is een brekende wijziging? Zouden we de hele API opnieuw versienummeren of slechts bepaalde endpoints? Bij SparkPost werken we met meerdere teams aan verschillende delen van onze API. Binnen die teams werken mensen op verschillende momenten aan verschillende endpoints. Daarom is het erg belangrijk dat onze API consistent is in het gebruik van conventies. Dit was groter dan alleen versiebeheer.
We hebben een bestuursgroep opgericht met onder meer ingenieurs die elk team vertegenwoordigen, een lid van het Product Management-team en onze CTO. Deze groep is verantwoordelijk voor het opstellen, documenteren en handhaven van onze API-conventies binnen alle teams. Een API-governance Slack-kanaal is ook handig voor levendige debatten over het onderwerp.
De bestuursgroep identificeerde verschillende manieren waarop wijzigingen aan de API kunnen worden geïntroduceerd die voordelig zijn voor de gebruiker en geen brekende wijzigingen vormen.
Wijzigingstype | Brekend beschouwd? | Reden |
|---|---|---|
Nieuwe bron of endpoint | Nee | Heeft geen invloed op bestaande integraties |
Nieuwe optionele parameter | Nee | Bestaande verzoeken blijven geldig |
Nieuwe optionele JSON-sleutel | Nee | Clients kunnen het veilig negeren |
Nieuw responsveld | Nee | Achterwaarts compatibel voor gebruikers |
Nieuwe vereiste parameter | Ja | Breekt bestaande verzoeken |
Nieuwe vereiste POST-sleutel | Ja | Maakt bestaande payloads ongeldig |
Verwijderen van een endpoint | Ja | Bestaande integraties falen |
Veranderen van standaardgedrag | Ja | Wijzigt verwachte uitkomsten |
Deze omvatten:
Een nieuwe bron of API-endpoint
Een nieuwe optionele parameter
Een wijziging aan een niet-openbaar API-endpoint
Een nieuwe optionele sleutel in de JSON POST-body
Een nieuwe sleutel die in de JSON-responsetcode wordt geretourneerd
Daarentegen omvatte een brekende wijziging alles wat de integratie van een gebruiker zou kunnen breken, zoals:
Een nieuwe vereiste parameter
Een nieuwe vereiste sleutel in POST-bodies
Verwijderen van een bestaand endpoint
Verwijderen van een bestaande endpoint-aanroepmethode
Een materieel ander intern gedrag van een API-aanroep – zoals een wijziging in het standaardgedrag.
Met een versie-conventie geselecteerd hadden we meer vragen. Wanneer zouden we de versie verhogen? Wat is een brekende wijziging? Zouden we de hele API opnieuw versienummeren of slechts bepaalde endpoints? Bij SparkPost werken we met meerdere teams aan verschillende delen van onze API. Binnen die teams werken mensen op verschillende momenten aan verschillende endpoints. Daarom is het erg belangrijk dat onze API consistent is in het gebruik van conventies. Dit was groter dan alleen versiebeheer.
We hebben een bestuursgroep opgericht met onder meer ingenieurs die elk team vertegenwoordigen, een lid van het Product Management-team en onze CTO. Deze groep is verantwoordelijk voor het opstellen, documenteren en handhaven van onze API-conventies binnen alle teams. Een API-governance Slack-kanaal is ook handig voor levendige debatten over het onderwerp.
De bestuursgroep identificeerde verschillende manieren waarop wijzigingen aan de API kunnen worden geïntroduceerd die voordelig zijn voor de gebruiker en geen brekende wijzigingen vormen.
Wijzigingstype | Brekend beschouwd? | Reden |
|---|---|---|
Nieuwe bron of endpoint | Nee | Heeft geen invloed op bestaande integraties |
Nieuwe optionele parameter | Nee | Bestaande verzoeken blijven geldig |
Nieuwe optionele JSON-sleutel | Nee | Clients kunnen het veilig negeren |
Nieuw responsveld | Nee | Achterwaarts compatibel voor gebruikers |
Nieuwe vereiste parameter | Ja | Breekt bestaande verzoeken |
Nieuwe vereiste POST-sleutel | Ja | Maakt bestaande payloads ongeldig |
Verwijderen van een endpoint | Ja | Bestaande integraties falen |
Veranderen van standaardgedrag | Ja | Wijzigt verwachte uitkomsten |
Deze omvatten:
Een nieuwe bron of API-endpoint
Een nieuwe optionele parameter
Een wijziging aan een niet-openbaar API-endpoint
Een nieuwe optionele sleutel in de JSON POST-body
Een nieuwe sleutel die in de JSON-responsetcode wordt geretourneerd
Daarentegen omvatte een brekende wijziging alles wat de integratie van een gebruiker zou kunnen breken, zoals:
Een nieuwe vereiste parameter
Een nieuwe vereiste sleutel in POST-bodies
Verwijderen van een bestaand endpoint
Verwijderen van een bestaande endpoint-aanroepmethode
Een materieel ander intern gedrag van een API-aanroep – zoals een wijziging in het standaardgedrag.
The Big 1.0
Naarmate we deze conventies documenteerden en bespraken, kwamen we ook tot de conclusie dat het in ieders (inclusief ons!) belang was om te vermijden dat we ingrijpende veranderingen aan de API aanbrachten, aangezien het beheren van meerdere versies behoorlijk wat overhead met zich meebrengt. We besloten dat er een paar dingen waren die we met onze API zouden moeten oplossen voordat we ons zouden committeren aan "v1".
Het verzenden van een eenvoudige e-mail vereiste veel te veel moeite. Om "de eenvoudige dingen eenvoudig te houden" hebben we het POST-body bijgewerkt om ervoor te zorgen dat zowel eenvoudige als complexe gebruiksscenario's worden ondersteund. Het nieuwe formaat was ook meer toekomstbestendig. Ten tweede hebben we een probleem met het Metrics endpoint aangepakt. Dit eindpunt gebruikte een "group_by" parameter die het formaat van de GET-responsbody zou wijzigen zodat de eerste sleutel de waarde van de group_by parameter zou zijn. Dat leek niet erg RESTful, dus we hebben elk group_by gesplitst in een apart eindpunt. Ten slotte hebben we elk eindpunt gecontroleerd en hier en daar kleine wijzigingen aangebracht om ervoor te zorgen dat ze aan de normen voldeden.
Naarmate we deze conventies documenteerden en bespraken, kwamen we ook tot de conclusie dat het in ieders (inclusief ons!) belang was om te vermijden dat we ingrijpende veranderingen aan de API aanbrachten, aangezien het beheren van meerdere versies behoorlijk wat overhead met zich meebrengt. We besloten dat er een paar dingen waren die we met onze API zouden moeten oplossen voordat we ons zouden committeren aan "v1".
Het verzenden van een eenvoudige e-mail vereiste veel te veel moeite. Om "de eenvoudige dingen eenvoudig te houden" hebben we het POST-body bijgewerkt om ervoor te zorgen dat zowel eenvoudige als complexe gebruiksscenario's worden ondersteund. Het nieuwe formaat was ook meer toekomstbestendig. Ten tweede hebben we een probleem met het Metrics endpoint aangepakt. Dit eindpunt gebruikte een "group_by" parameter die het formaat van de GET-responsbody zou wijzigen zodat de eerste sleutel de waarde van de group_by parameter zou zijn. Dat leek niet erg RESTful, dus we hebben elk group_by gesplitst in een apart eindpunt. Ten slotte hebben we elk eindpunt gecontroleerd en hier en daar kleine wijzigingen aangebracht om ervoor te zorgen dat ze aan de normen voldeden.
Naarmate we deze conventies documenteerden en bespraken, kwamen we ook tot de conclusie dat het in ieders (inclusief ons!) belang was om te vermijden dat we ingrijpende veranderingen aan de API aanbrachten, aangezien het beheren van meerdere versies behoorlijk wat overhead met zich meebrengt. We besloten dat er een paar dingen waren die we met onze API zouden moeten oplossen voordat we ons zouden committeren aan "v1".
Het verzenden van een eenvoudige e-mail vereiste veel te veel moeite. Om "de eenvoudige dingen eenvoudig te houden" hebben we het POST-body bijgewerkt om ervoor te zorgen dat zowel eenvoudige als complexe gebruiksscenario's worden ondersteund. Het nieuwe formaat was ook meer toekomstbestendig. Ten tweede hebben we een probleem met het Metrics endpoint aangepakt. Dit eindpunt gebruikte een "group_by" parameter die het formaat van de GET-responsbody zou wijzigen zodat de eerste sleutel de waarde van de group_by parameter zou zijn. Dat leek niet erg RESTful, dus we hebben elk group_by gesplitst in een apart eindpunt. Ten slotte hebben we elk eindpunt gecontroleerd en hier en daar kleine wijzigingen aangebracht om ervoor te zorgen dat ze aan de normen voldeden.
Nauwkeurige Documentatie
Het is belangrijk om nauwkeurige en bruikbare API-documentatie te hebben om breaking changes te vermijden, of ze nu opzettelijk of onbedoeld zijn. We hebben besloten om een eenvoudige benadering van API-documentatie te gebruiken door gebruik te maken van een Markdown-taal genaamd API Blueprint en onze documentatie in Github beheren. Onze gemeenschap draagt bij aan en verbetert deze open source documenten. We onderhouden ook een niet-openbare set documenten in Github voor interne API's en endpoints.
Aanvankelijk publiceerden we onze documenten op Apiary, een geweldig hulpmiddel voor prototyping en publiceren van API-documentatie. Echter, het inbedden van Apiary in onze website werkt niet goed op mobiele apparaten, daarom gebruiken we nu Jekyll om in plaats daarvan statische documenten te genereren. Onze nieuwste SparkPost API-documentatie laadt nu snel en werkt goed op mobiele apparaten, wat belangrijk is voor ontwikkelaars die niet altijd achter hun computer zitten.
Het is belangrijk om nauwkeurige en bruikbare API-documentatie te hebben om breaking changes te vermijden, of ze nu opzettelijk of onbedoeld zijn. We hebben besloten om een eenvoudige benadering van API-documentatie te gebruiken door gebruik te maken van een Markdown-taal genaamd API Blueprint en onze documentatie in Github beheren. Onze gemeenschap draagt bij aan en verbetert deze open source documenten. We onderhouden ook een niet-openbare set documenten in Github voor interne API's en endpoints.
Aanvankelijk publiceerden we onze documenten op Apiary, een geweldig hulpmiddel voor prototyping en publiceren van API-documentatie. Echter, het inbedden van Apiary in onze website werkt niet goed op mobiele apparaten, daarom gebruiken we nu Jekyll om in plaats daarvan statische documenten te genereren. Onze nieuwste SparkPost API-documentatie laadt nu snel en werkt goed op mobiele apparaten, wat belangrijk is voor ontwikkelaars die niet altijd achter hun computer zitten.
Het is belangrijk om nauwkeurige en bruikbare API-documentatie te hebben om breaking changes te vermijden, of ze nu opzettelijk of onbedoeld zijn. We hebben besloten om een eenvoudige benadering van API-documentatie te gebruiken door gebruik te maken van een Markdown-taal genaamd API Blueprint en onze documentatie in Github beheren. Onze gemeenschap draagt bij aan en verbetert deze open source documenten. We onderhouden ook een niet-openbare set documenten in Github voor interne API's en endpoints.
Aanvankelijk publiceerden we onze documenten op Apiary, een geweldig hulpmiddel voor prototyping en publiceren van API-documentatie. Echter, het inbedden van Apiary in onze website werkt niet goed op mobiele apparaten, daarom gebruiken we nu Jekyll om in plaats daarvan statische documenten te genereren. Onze nieuwste SparkPost API-documentatie laadt nu snel en werkt goed op mobiele apparaten, wat belangrijk is voor ontwikkelaars die niet altijd achter hun computer zitten.
Deployment scheiden van Release
We leerden al vroeg de waardevolle truc van het scheiden van een implementatie van een release. Op deze manier is het mogelijk om vaak veranderingen door te voeren wanneer ze klaar zijn via continue levering en implementatie, maar we kondigen ze niet altijd publiekelijk aan of documenteren ze niet altijd tegelijkertijd. Het is niet ongewoon voor ons om een nieuwe API-endpoint te implementeren of een verbetering aan een bestaand API-endpoint te doen en deze te gebruiken binnen de UI of met interne tools voordat we het publiekelijk documenteren en ondersteunen. Op die manier kunnen we enkele aanpassingen doen voor bruikbaarheid of naleving van standaarden zonder ons zorgen te maken over het maken van een gevreesde breaking change. Zodra we tevreden zijn met de verandering voegen we het toe aan onze openbare documentatie.
We leerden al vroeg de waardevolle truc van het scheiden van een implementatie van een release. Op deze manier is het mogelijk om vaak veranderingen door te voeren wanneer ze klaar zijn via continue levering en implementatie, maar we kondigen ze niet altijd publiekelijk aan of documenteren ze niet altijd tegelijkertijd. Het is niet ongewoon voor ons om een nieuwe API-endpoint te implementeren of een verbetering aan een bestaand API-endpoint te doen en deze te gebruiken binnen de UI of met interne tools voordat we het publiekelijk documenteren en ondersteunen. Op die manier kunnen we enkele aanpassingen doen voor bruikbaarheid of naleving van standaarden zonder ons zorgen te maken over het maken van een gevreesde breaking change. Zodra we tevreden zijn met de verandering voegen we het toe aan onze openbare documentatie.
We leerden al vroeg de waardevolle truc van het scheiden van een implementatie van een release. Op deze manier is het mogelijk om vaak veranderingen door te voeren wanneer ze klaar zijn via continue levering en implementatie, maar we kondigen ze niet altijd publiekelijk aan of documenteren ze niet altijd tegelijkertijd. Het is niet ongewoon voor ons om een nieuwe API-endpoint te implementeren of een verbetering aan een bestaand API-endpoint te doen en deze te gebruiken binnen de UI of met interne tools voordat we het publiekelijk documenteren en ondersteunen. Op die manier kunnen we enkele aanpassingen doen voor bruikbaarheid of naleving van standaarden zonder ons zorgen te maken over het maken van een gevreesde breaking change. Zodra we tevreden zijn met de verandering voegen we het toe aan onze openbare documentatie.
