Taal van API query-parameters

Organisaties Digitaal Stelsel Omgevingswet
#1

Na het doornemen van de API-strategie en de BAG API documentatie heb ik een aantal vragen met betrekking tot deze richtlijnen, specifiek over de taal van de API.

API-11 geeft aan dat de “expand” query-parameter wordt gebruikt, API-12, heeft het over de “fields” query-parameter. Beide Engels. API-35, API-36 en API-46 hebben het respectievelijk over “sorteer”, “zoek” en “pagina” query-parameters. Deze zijn dus weer Nederlands. De reden die gegeven wordt in API-07 geeft hier onvoldoende reden voor. Waarom zou er een Engels begrippenkader zijn voor de eerste 2, en een Nederlandse voor de laatste 3?

De BAG API gebruikt overigens de query-parameter “page” voor pagina’s. Dit wijkt dan ook weer af van de strategie. Zie: https://data.pdok.nl/bag/api/v1/#tag/Pand

Moet dit niet gewoon consistent in het Engels?

#2

@dvh
Dimitri, kun jij hier op reageren?

#3

@Joeri dank voor de feedback. De huidige versie van de BAG API is niet conform de API Strategie omdat deze er eerder was dan de API Strategie zelf :wink:

Voor wat betreft de overige punten ben ik het eens dat dit consistent moet zijn; ongeacht of het Engels of Nederlands is, is het logisch om dit allemaal in dezelfde taal te doen. Op DSO niveau is reeds besloten dat Nederlands leidend is, dus zouden ‘fields’ en ‘expand’ logischerwijs ook vertaald moeten worden. Ik neem het mee met de feedback voor de API Strategie 1.1 versie!

#4

Ah, ik wist niet dat de BAG API er eerder was. Het ziet er namelijk uit alsof er best wat punten overeenkomen met de strategie :+1: maar wellicht is de BAG API ook gebruikt ter inspiratie.

Ik ben op dit forum terecht gekomen omdat de DSO, API- en URI-strategie ons aansprak vanwege de moderne aanpak. Er zijn hier en daar wat puntjes waar we vraagtekens bij hebben, dus wellicht kom ik binnenkort nog met enkele vragen of opmerkingen. Helemaal top als deze meegenomen worden in de vervolgversie!

1 like