Versies en wijzigingen
/v1 blijft compatibel — wat telt als een brekende wijziging, hoe we die aankondigen, en elke wijziging aan de API.
De versie staat in het pad: /api/v1. Binnen /v1 groeit de API alleen; niets waar je
op rekent, verdwijnt of krijgt een andere betekenis.
Wat binnen v1 kan veranderen
Nieuwe endpoints, nieuwe optionele velden in een verzoek, nieuwe velden in een antwoord of een webhook-bericht, nieuwe foutcodes, nieuwe soorten gebeurtenissen en nieuwe waarden van een opsomming in een antwoord. Geen daarvan is een brekende wijziging, dus:
- negeer velden die je niet kent;
- negeer gebeurtenissen waarop je niet geabonneerd bent of die je niet kent;
- programmeer voorzichtig rond een waarde van een opsomming die je niet herkent — er is geen belofte in welke richting dan ook.
De namen version, changedBy en previous zijn in elke leesvorm gereserveerd.
Wat een brekende wijziging is
Iets weghalen of hernoemen, een veld verplicht maken, een type versmallen, of veranderen
wat iets betekent. Een brekende wijziging komt als /v2. /v1 blijft daarna minstens
zes maanden werken, de wijziging wordt op deze pagina aangekondigd, en de antwoorden van
de oude versie dragen in de tussentijd de headers Deprecation en Sunset.
Wijzigingen
Elke wijziging aan het contract, de nieuwste eerst. De eerste regel verschijnt op de dag dat de API uitkomt.