Versiebeheer

Huidige versie

v1. Alle endpoints staan onder /v1/…. Pin geen versie in je client-URLs en je integratie breekt zodra we v2 uitrollen.

Wat telt als breaking change

• Een veld verwijderen uit een response.
• Een veld hernoemen.
• Het type van een veld veranderen (bv. number → string).
• De validatie van een bestaand endpoint strenger maken zodat eerder-geaccepteerde requests worden geweigerd.
• De URL van een endpoint veranderen.

Wat niet breaking is

• Nieuwe optionele response-velden toevoegen.
• Nieuwe endpoints toevoegen.
• Nieuwe query-parameters toevoegen waarvan de defaults huidig gedrag behouden.
• Nieuwe enum-waarden toevoegen (bv. een nieuw allergeen). Clients moeten onbekende enum-waarden netjes afhandelen.

Deprecation-beleid

Wanneer we uiteindelijk v2 uitrollen:

• v1 blijft minstens 12 maanden operationeel na de release van v2.
• Deprecation-tijdlijn wordt vooraf aangekondigd via de changelog en per e-mail aan alle actieve accounts.
• Responses op de gedepreceerde versie bevatten een Sunset header volgens RFC 8594.

Beta-features

Nieuwe endpoints kunnen onder een /v1/beta/…-prefix vrijgegeven worden. Alles onder beta kan zonder waarschuwing veranderen en valt buiten versie-garanties tot promotie.