melsk-r
commented
3 years ago JBo: Niet overnemen HK: Discussie RM: Niet overnemen MV: Niet overnemen GJ: Niet overnemen JBi: Aanbeveling ipv regel?
JBo: Niet als generieke design decision. Neemt niet weg dat hier binnen een project voor gekozen kan worden. MV: Eens met JBo HK: Waarom kan dit geen generieke DD zijn? Wat zijn de tegenargumenten? JBo: @HK, In lang niet alle administraties die we met API's willen ontsluiten zijn UUID's opgenomen als identificatie. BV. de basiregistraties kennen gewoon de identificatievelden (KvKnummer, burgerservicenummer, KadastraalOnroerendeZaakidentificatie) als unieke identificatie. Die kan je dus niet dwingen om UUID's te gaan gebruiken. Dit is dus een beslissing die binnen een specifiek project genomen wordt. JBi: Lijkt me wel waardevol om deze 'regel' in de vorm van een aanbeveling te hebben voor nieuwe situaties. Dan werken we in ieder geval op termijn toe naar uniformiteit. GJ: in deze vorm te specifiek voor een generieke design decision.
De ID-parameter, hieronder aangeduid met {uuid} wordt gebruikt om via de URL een enkel object van een bepaald type resource te vinden. Bijvoorbeeld een Zaak:
URL Voorbeeld
Een UUID (versie 4) is in de praktijk altijd uniek, zonder dat deze centraal hoeft te worden bijgehouden. Deze keuze laat onverlet de mogelijkheid om op andere manieren bij een enkel object te komen, zoals op een combinatie van velden die samen uniek zijn, zoals bronorganisatie en zaakidentificatie:
Achtergrond De paden van API endpoints bevatten referenties naar de objecten in de achterliggende datastore. Deze parameters zouden semantisch ingevuld kunnen worden, zoals gebruikmaken van bronorganisatie en zaakidentificatie voor een zaak. Echter, na analyse blijkt dat dit lastig consequent toe te passen is door de hele de API heen. Tevens wekt het de indruk dat deze parameters voldoende zijn om een Zaak te vinden maar dat is niet correct. De volledige URL is nodig voor het opvragen van een enkele Zaak.
Daarom is besloten om gebruik te maken van UUID (versie 4) voor deze parameters. De motivatie is verder dat deze:
ISO-8601 durations voor uitdrukken van duur Voor het uitdrukken van duur wordt gebruikt gemaakt van ISO-8601 durations. Dit sluit aan bij ISO-8601 weergave van timestamps doorheen de API.