search

VNG-Realisatie / gemma-zaken

Samen ontwikkelen van API's voor Zaakgericht werken
https://vng-realisatie.github.io/gemma-zaken/
Other
41 stars 27 forks source link

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

Open EduardWitteveen opened 1 week ago

EduardWitteveen commented 1 week ago

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:

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 commented 1 week ago

Wat een goed idee! 💯

HenriKorver commented 6 days ago

Hiervoor kun je al de HEAD operation gebruiken. Bijvoorbeeld:

https://vng-realisatie.github.io/gemma-zaken/standaard/zaken/redoc-1.5.1#tag/zaken/operation/zaak_headers

Deze operatie geeft alleen de headers terug. Dit betekent dat je de versie van de API kunt bevragen zonder de daadwerkelijke inhoud van de respons te downloaden.

EduardWitteveen commented 5 days ago

Kun je uitleggen hoe ik HEAD zou moeten gebruiken. Ik begrijp het gebruik van de HEAD /zaken/{uuid} niet, deze vereist ook al dat er een zaak-uuid bekend is.

Wij gebruiken voor de verschillende versies/varianten een factory-pattern. Om een uuid op te halen is het ook al nodig om bevragingen te doen op de zrc, waardoor het lastiger wordt om bijv. te gebruiken. Mogelijk dat er de veronderstelling is dat wij uuid's opslaan, maar wij beginnen eigenlijk altijd met een zaak-identificatie/bsn(/kvk) bij het bevragen.

HenriKorver commented 5 days ago

Kun je uitleggen hoe ik HEAD zou moeten gebruiken. Ik begrijp het gebruik van de HEAD /zaken/{uuid} niet, deze vereist ook al dat er een zaak-uuid bekend is.

Je hebt gelijk, ik heb me vergist: de HEAD-operatie lost jouw probleem inderdaad niet op. HEAD wordt voornamelijk gebruikt om de etag waarde op te halen m.b.t. caching en dan is de uuid van de zaak wel bekend. GET /info lijkt mij een voor de hand liggende oplossing.

HenriKorver commented 5 days ago

Nog een vraag. Allerlei informatie over de API (zoals versienummer) staat ook in de OAS.

openapi: 3.0.3
info:
  title: Zaken API
  version: 1.5.2

Waarom gebruik je die niet om het versienummer (etc.) op te halen?