STD-0002: API-versiebeheer en compatibiliteit¶

Documentgegevens¶

Doel en reikwijdte¶

Deze standaard maakt wijzigingen aan API-contracten voorspelbaar voor producenten en consumenten. Zij geldt voor extern gebruikte API's en API's tussen teams. Interne, uitsluitend binnen één deploymenteenheid gebruikte interfaces kunnen gemotiveerd buiten scope vallen.

Normatieve bepalingen¶

• Iedere API in scope MOET een expliciet, machineleesbaar contract en een herkenbare major contractversie hebben.
• Een API MOET binnen één CIZ-profiel consequent hetzelfde versioneringsmechanisme gebruiken; pad, header en mediatype MOGEN NIET willekeurig worden gemengd.
• Een incompatibele contractwijziging MOET een nieuwe major krijgen. Backward-compatible toevoegingen MOGEN binnen dezelfde major worden gepubliceerd.
• Bestaande geldige requests en gedocumenteerde responsevelden MOETEN binnen een ondersteunde major compatibel blijven.
• Consumenten BEHOREN onbekende optionele responsevelden te tolereren.
• Foutresponses MOETEN een stabiele niet-gevoelige foutcode, menselijke samenvatting en correlation ID bevatten. RFC 9457 is de voorkeursbasis totdat een CIZ-API-profiel anders bepaalt.
• Breaking changes MOETEN vooraf worden gepubliceerd met impact, migratiepad, tijdlijn en beëindigingsdatum.
• Producenten MOETEN contract, compatibiliteitstests, changelog en deprecationcommunicatie onderhouden.
• Consumenten MOETEN bewust een major kiezen, contracttests uitvoeren en binnen de afgesproken termijn migreren.
• Tijd- en tekstvelden MOETEN voldoen aan STD-0001.

Rationale¶

Expliciete majorversies begrenzen incompatibele wijzigingen en geven ketenpartners een beheersbaar migratiepad. Een versie per productrelease veroorzaakt onnodige varianten; volledig onversiede contracten maken breaking changes onvoldoende zichtbaar.

Uitzonderingen en risicoacceptatie¶

Een uitzondering MOET API, consumenten, reden, compatibiliteitsrisico, migratieactie, eigenaar en einddatum bevatten. Een spoedwijziging vanwege een actief beveiligingsrisico KAN een verkorte termijn krijgen, mits impact en communicatie aantoonbaar zijn beoordeeld.

Naleving en vereiste bewijslast¶

• gepubliceerd machineleesbaar contract en versiebeleid;
• contractlinting en consumer/provider-contracttests;
• compatibiliteitsdiff in CI;
• changelog, deprecationmelding en gebruikstelemetrie;
• controle op gestandaardiseerde, niet-gevoelige foutresponses.

Implementatieprofielen¶

Een CIZ-API-profiel MOET nog vastleggen waar de majorversie wordt geplaatst, welke RFC 9457-extensies gelden en welke standaardtermijnen worden gebruikt. Tot die vaststelling MOET een oplossing de gekozen conventie expliciet documenteren en consistent toepassen.

Externe mappings en bronnen¶

Wijzigingshistorie¶