𝟵 𝗔𝗣𝗜-𝘄𝗶𝗷𝘇𝗶𝗴𝗶𝗻𝗴𝗲𝗻 𝗱𝗶𝗲 𝗷𝗲 𝗮𝗽𝗽 𝗯𝗿𝗲𝗸𝗲𝗻

"We hebben niets kapotgemaakt. We hebben alleen de response opgeschoond."

Die woorden leiden vaak tot crashes. Een mobiele app faalt. Een partnerintegratie geeft onzin terug. Je hebt de structuur van data veranderd waar anderen op vertrouwen.

Gevaarlijke wijzigingen lijken vaak op het opruimen van zaken. Ze passeren code reviews en tests. De fouten ontstaan in code die je niet kunt zien.

Hier zijn negen wijzigingen die veilig aanvoelen, maar dat niet zijn.

• Velden hernoemen Het veranderen van userId naar user_id voor de consistentie breekt clients. Een hernoeming is een verwijdering en een toevoeging. Het verwijderen is wat de problemen veroorzaakt. Veilige aanpak: Voeg het nieuwe veld toe. Houd het oude veld aan. Maak het deprecated. Verwijder het pas veel later.

• Een veld optioneel maken Een veld was er altijd. Nu is het soms null. De client-code crasht wanneer deze het probeert te verwerken. Veilige aanpak: Behandel "altijd aanwezig" als een belofte. Als een veld optioneel wordt, gebruik dan een nieuwe versie.

• Ongebruikte velden verwijderen Je kunt niet zien hoe je consumenten je data gebruiken. "Ongebruikt" betekent alleen dat het door jou niet wordt gebruikt. Veilige aanpak: Meet het gebruik van velden in productie voordat je iets verwijdert.

• Inputtypen beperken Het veranderen van een string naar een enum of een number naar een integer breekt requests. Het verbreden van een input is veilig. Het beperken ervan is een breaking change. Veilige aanpak: Maak alleen de inputs die je accepteert ruimer. Het aanscherpen vereist een nieuwe versie.

• Standaardwaarden wijzigen Het veranderen van een standaardwaarde van false naar true verandert het gedrag zonder een foutmelding te geven. Dit breekt de logica stilletjes. Veilige aanpak: Behandel een wijziging in de standaardwaarde als een breaking change.

• Verplichte velden toevoegen Het toevoegen van tenantId en dit verplicht maken, breekt elke bestaande client. Ze krijgen een 400-foutmelding. Veilige aanpak: Nieuwe velden moeten optioneel zijn of een nieuwe versie vereisen.

• Errorformaten wijzigen Het veranderen van een 400 naar een 422 of het wijzigen van de error body breekt de code voor foutafhandeling. Veilige aanpak: Errorformaten zijn contracten. Versioneer ze zoals alles wat anders.

• Enum-waarden aanpassen Het hernoemen van "active" naar "ACTIVE" breekt clients. Het verwijderen van een waarde breekt clients met strikte logica. Veilige aanpak: Enum-waarden zijn voor altijd. Voeg ze voorzichtig toe. Hernoem of verwijder ze nooit zonder een nieuwe major version.

• De betekenis van data veranderen Het veranderen van een datum van Unix-seconden naar ISO-8601 of het veranderen van paginering van offset naar cursor breekt alles. Een schema-diff detecteert dit misschien niet eens. Veilige aanpak: Leg formaten expliciet vast. Vergelijk echte payloads, niet alleen de specificatie.

Vertrouw niet op je gevoel. Vergelijk elke wijziging met het productiecontract in je CI. Een mens kan een hernoemd veld over het hoofd zien. Een diff-tool zal dat niet doen.

Bron: https://dev.to/deepaksatyam/9-api-changes-that-look-backwards-compatible-but-arent-1bk0