VDAB wijzigingsbeleid voor API's

De aankondigingsperiode is afhankelijk van het type wijziging:

• 'Breaking changes' (en de bijbehorende introductie van een nieuwe API-versie) communiceren we minimaal 2 maanden vóór de nieuwe API-versie in productie gaat. 
  • In deze communicatie berichten we:
    • wat de toekomstige releasedatum zal zijn
    • wat er zal wijzigen 
    • welke acties je moet ondernemen wanneer je overschakelt naar de nieuwe versie
• Om de continuïteit van je applicatie naar je eindgebruikers toe te garanderen, adviseren we je om al stappen te ondernemen en aanpassingen door te voeren vóór de releasedatum van de breaking change.
• 'Non-breaking changes' communiceren we minimaal 2 weken  vóór de inproductiestelling. We berichten wat de toekomstige releasedatum zal zijn en wat precies zal wijzigen.

Opgelet!

We kunnen zonder voorafgaande kennisgeving wijzigingen aanbrengen als deze  worden doorgevoerd naar aanleiding van kritieke fouten of wettelijke, beveiligings- of privacybelangen.

Een breaking change is een wijziging aan de API die er potentieel voor zorgt dat de integratie van deze API in jouw applicatie niet meer werkt. Een breaking change vereist mogelijk dat je je applicatie bijwerkt om storingen te voorkomen.

Voorbeelden

Hieronder volgen enkele courante wijzigingen die als 'breaking' worden gekwalificeerd:

• een wijziging in:
  •  het formaat van de responsdata voor één of meerdere API-aanroepen
  • de bestaande authenticatiemethodes
  • het verzoek- of antwoordtype
  • de oorspronkelijke functionaliteit van een endpoint
• de verwijdering van:
  • een deel van de API zoals die oorspronkelijk gereleased werd
  • een bestaande parameter, een verzoek- of antwoordveld
• de toevoeging van:
  • een verplichte parameter of een verzoekveld zonder een standaardwaarde toe te kennen aan deze nieuwe parameter of dit verzoekveld
  • nieuwe en striktere validatie voor een verzoek

Een non-breaking change beschouwen we als een verandering die geen impact heeft op applicaties die gebruikmaken van de API. Een non-breaking change brengt met zich mee dat alle eerdere/voorafgaande functionaliteiten niet in het gedrang komen waardoor de API achterwaarts compatibel is.

Deze verandering kan dan op jouw eigen tempo en naar jouw inzicht of nood toegevoegd worden aan je bestaande applicatie.

Voorbeelden 

Hieronder volgen enkele courante wijzigingen die als 'non-breaking' worden gekwalificeerd:

• de toevoeging van nieuwe:
  • optionele parameters, verzoek- of antwoordvelden
  • verplichte parameters, verzoek- of antwoordvelden met een standaardwaarde 
  • endpoints
  • HTTP-methodes voor bestaande endpoints
  • waardes bij bestaande tekstvelden
• de toevoeging van een optionele 'request header'
• een wijziging van:
  • de volgorde van velden die in een antwoord worden teruggestuurd
  • de lengte / grootte (indien groter dan voorheen) van responsdata van een bepaald veld
  • de inhoud van fout- en waarschuwingsboodschappen die het endpoint terugstuurt
• de aanpassing van foutieve HTTP-respons- en foutcodes naar correcte codes
• het niet aanwezig zijn of null zijn van optionele velden
• bugfixes

Voor de oudere versies van onze API’s voorzien we een uitfasering van 6 maanden. Dat houdt in dat we zowel de oude als de nieuwe versie nog ter beschikking stellen en ondersteunen gedurende deze periode, maar na het einde hiervan enkel nog de nieuwe versie van de API aanbieden.

VDAB streeft ernaar zijn API’s up-to-date te houden, uit te breiden of te vernieuwen via non-breaking changes, maar zal in uitzonderlijke en noodzakelijke gevallen wél de stap naar een nieuwe versie zetten.

Dit introduceren van breaking changes trachten we steeds minimaal te houden.