Als server/client ontwikkelaar wil ik een duidelijke beschrijving van de API-version response header zodat ik deze kan parsen.

[sergei-maertens]

Alle endpoints in de API's (zaken, documenten, catalogi, besluiten, autorisaties, notificaties) documenteren de API-version response header, echter deze documentatie is onvolledig: deze wordt nu enkel als string gedocumenteerd.

Ik mis hierbij:

• de markering dat de header verplicht is (essentieel om As a team member, I want the APIs to support version negotation #1289 te kunnen realiseren, was destijds een verplichting van de DSO API richtlijnen die overgenomen was)
• een pattern om het formaat tot semver {major}.{minor}.{patch} te beperken, dit zou de volgende regex moeten zijn: [0-9]+\.[0-9]+\.[0-9]+

Als client developer die meerdere API-versies ondersteunt zijn deze garanties noodzakelijk - dit laat toe om features van nieuwere versies te gebruiken indien ze beschikbaar zijn, terwijl deze op oudere versies tot foutmeldingen zou leiden. De client kijkt hierbij naar welke API versie aangeboden is en parset de versie-string om vervolgens de beslissing te kunnen maken.

Ik zie nu al bij verschillende server-implementaties dat ze afwijken van het gedrag wat de bedoeling was toen deze response header toegevoegd was, en afwijken van hoe het gebouwd was in de referentie-implementaties indertijd. Ik wil welles-nietes discussies op dit onderwerp vermijden door naar de API-specificatie te kunnen wijzen.

M.i. is dit eigenlijk een bug in de API-specificatie doordat het onvolledig is, en geen breaking change doordat dingen strikter gemaakt worden - het was altijd als dusdanig bedoeld.

[HenriKorver]

Het lijkt mij een goed idee om de API-version header verplicht te maken en stricter te beschrijven zodat de versie in het juiste semver formaat wordt ingevuld.

[johannesbattjes]

Eens met dit voorstel, het maakt de ZGW-standaard weer duidelijker