Toevoegen van een dedicated endpoint voor het opvragen van de API-versie

[EduardWitteveen]

Bij gebruik van de Zaken API willen we graag weten welke versie van de API wordt ondersteund door de server, bijvoorbeeld om functies zoals expand (beschikbaar vanaf versie 1.5.0) te kunnen gebruiken. Op dit moment is het alleen mogelijk om de API-versie via een response-header te achterhalen, maar dit vereist dat we een willekeurige functionele call (GET/POST) uitvoeren, wat niet netjes of efficiënt voelt.

Huidige situatie:

• De versie-informatie (API-Version) is beschikbaar in de response-header van een functionele API-call.
• Dit betekent dat een willekeurige bevraging nodig is, puur om de versie te bepalen.
• Dit maakt de implementatie minder overzichtelijk en introduceert onnodige overhead, vooral bij het starten van een nieuwe client.

Voorstel:
Voeg een speciaal endpoint toe, zoals /info/, dat is bedoeld voor het opvragen van versie-informatie en eventueel andere metadata over de API.

Voordelen:

1. Efficiëntie: Clients kunnen snel en doelgericht de API-versie ophalen zonder functionele endpoints te belasten.
2. Netheid: Het voorkomt het gevoel van een "workaround" en zorgt voor een gestructureerde aanpak.
3. Flexibiliteit: Een /info/-endpoint kan in de toekomst worden uitgebreid met andere nuttige informatie (bijvoorbeeld ondersteunde functionaliteiten of serverstatus).

Mogelijke implementatie:
Request:

GET /info/

Response:

{
    "version": "1.5.0",
    "description": "Zaken API",
    "productName": "OpenZaak",
    "productVersion": "1.15.0"
    "productBuild": "20241120"
}

Vraag:
Kan een dedicated endpoint zoals /info/ worden toegevoegd aan de standaard, zodat clients eenvoudiger en efficiënter versie-informatie kunnen ophalen?

@sanderdekroon : omdat dit handiger is

[sanderdekroon]

Wat een goed idee! 💯