Design rule over timezone is nog steeds verwarrend

[HenriKorver]

Design rule /core/date-time/timezone zegt dat timezone offsets wel in de request mogen worden gebruikt maar niet in de response. In de respons moet een datetime altijd in UTC formaat zijn (met Z als timezone offset).

Hiermee lijk je precies de verwarring te creëren die in Example 8 als onwenselijk wordt beschreven.

[TimvdLippe]

De toegevoegde noot over storage (https://logius-standaarden.github.io/Publicatie-Preview/API-Design-Rules/date-time/#/core/date-time/timezone), helpt dat bij het interpreteren van deze regel? Example 8 wordt voornamelijk voorkomen door /core/date-time/date-omit-time-portion en /core/date-time/timezone is er om maximale duidelijkheid aan de client te geven. Door deze afspraak expliciet in de design rules te zetten, kan het "gokken" en doen van aannames zoals in example 8 wordt beschreven niet meer voorkomen.

[TimvdLippe]

@HenriKorver We hebben offline hier even over gesproken. Zou #300 voldoende zijn om jouw interpretatie te verduidelijken?

[HenriKorver]

Ik heb nog steeds moeite met deze zin:

Fields in responses containing a datetime MUST be in UTC (e.g. Z as timezone offset).

Waarom kunnen API-providers niet net zoals de clients zelf bepalen welke timezone offset ze gebruiken bij het teruggeven van responses? We hebben al gespecificeerd dat het om date-time formaat gaat conform ISO8601, dus het is 100% helder hoe deze velden geïnterpreteerd moeten worden ongeacht welke timezone offsets de clients of api providers gebruiken. Als bijv. een WOZ API, die hoofdzakelijk in Nederland wordt gebruikt, datetime velden in "Zulu-formaat" gaat teruggeven, waarin zelfs de datum van de dag kan veranderen rond 00:00 's nachts, creëert dat eerder verwarring (precies die verwarring die Example 8 wordt beschreven) dan dat het helderheid schept. Dus naar mijn mening moet de API Provider zelf kunnen bepalen welke timezone offset gebruikt wordt bij het retourneren van datetime velden. Door te specificeren dat het format "date-time" is (conform ISO8601) is interpretatie volstrekt helder. Wat mij betreft kan de bovengenoemde regel uit design rule /core/date-time/timezone verwijderd worden.

[TimvdLippe]

@BvanRaaij wederom benieuwd naar jouw inzicht

[BvanRaaij]

Example 8 is geschreven om te onderbouwen dat je nooit datetime moet gebruiken als je alleen maar date nodig hebt (mi de meeste gemaakte fout waardoor idd datums omklappen door tz conversies). Blijkbaar roept dit voorbeeld nu verwarring op wanneer er wel datetime nodig is.

Het allerbelangrijkste bij API-standaarden is (voor mij) duidelijkheid en gebruiksvriendelijkheid (development experience, DX) voor de client(-implementator) (API Consumer). Ik heb mijn idee over date en datetime daarom oorspronkelijk gebaseerd op The 5 laws of API dates and times

Law #2: Accept any timezone
Now that you have a tool set with ISO 8601 whereby you can capture relevant timezone offset data, use it! We are in a global age. Especially if your API is open to the public, you will unquestionably be dealing with consumers from around the globe. Do not make any assumptions about what timezone your API users will utilize.
Law #4: Return it in UTC
UTC will allow your API consumers the freedom to offset the date to whatever suits their needs. More importantly for you, your API team will not have to fret over calculating all of those offsets for every hit. Documenting and supporting your API, in terms of how you deal with dates, is simple: “you get UTC”.

Deze twee regels samen maken het erg gebruiksvriendelijk voor een client want hij mag zelf kiezen in welk format/tz hij aanlevert en krijgt een eenduidig antwoord terug dat hij zelf ook weer kan vertalen naar de timezone waarin hij de response wil gebruiken. De server schrijft dus niet voor aan de client met welke timezone hij moet werken: dat bepaalt de client zelf. De regel impliceert ook dat de client de data niet terugkrijgt in de tz waarin hij het zelf aanlevert (tenzij hij in Z aanlevert) en legt dus ook een verantwoordelijkheid bij de client om een juiste interpretatie te doen naar zijn tz.

Je zou binnen een NL context kunnen kiezen om alles in NL timezone (dus +01:00 of +02:00 in de zomertijd) terug te geven ipv in Z (+00:00), maar je houdt een vergelijkbaar probleem, nl dat een client het in een willekeurige tz mag aanleveren en in een andere tz terug gaat krijgen. Ik ben er daarom voor om het API platform simpel en consistent te laten werken en de de vrijheid en verantwoordelijkheid bij de client (consumer) te leggen en niet bij de provider (server)

[HenriKorver]

your API team will not have to fret over calculating all of those offsets for every hit. Documenting and supporting your API, in terms of how you deal with dates, is simple: “you get UTC”.

Ik ben het niet eens met deze stelling. Het moet in de eerste plaats de bedoeling zijn om het voor de client developers gemakkelijker te maken. Dat het API team iets meer werk moet doen om een gebruikersvriendelijke API aan te bieden is niet belangrijk, immers dat werk hoeft maar op één plek gedaan te worden en niet bij meerdere clients.

Je zou binnen een NL context kunnen kiezen om alles in NL timezone (dus +01:00 of +02:00 in de zomertijd) terug te geven ipv in Z (+00:00), maar je houdt een vergelijkbaar probleem, nl dat een client het in een willekeurige tz mag aanleveren en in een andere tz terug gaat krijgen.

Het probleem wordt dan juist veel kleiner want als je binnen dezelfde context werkt (bijvoorbeeld NL) dan is de kans juist veel kleiner dat het aangeleverde formaat afwijkt van het geretourneerde formaat, dus minder kans op verwarring. Bovendien en misschien is dit zelfs de bottom line heb je ook vaak te maken met simpele bevragingen waarbij geen aanlevering van datetime gegevens vooraf ging. Bijvoorbeeld: "Geef mij het registratietijdstip van een een bepaalde zaak." Dit tijdstip is nooit aangeleverd maar gewoon aangemaakt door de Zaak Registratie Component (Zaken API). Als ik dit soort bevragingen doe wil ik als een client in de context van een Nederlandse gemeente dit tijdstip gewoon in mijn eigen lokale offset terug krijgen en niet in UTC-formaat (met een Z) waarin de tijd een uur versprongen is, dat is alleen maar verwarrend.

[BvanRaaij]

Hi @HenriKorver : volgens mij zijn we het wel eens over die eerste stelling ik heb juist het stuk "API consumers the freedom to offset the date to whatever suits their needs" cursief gemaakt dat gaat over juist gebruiksgemak. Ik vind dat net als jij een veel belangrijker argument dat het ontwikkelgemak van het server-team.

Of iets makkelijk is voor een client-developer is overigens niet helemaal objectief te bepalen. Wat ik wel zie is dat jij jouw argumenten helemaal in een NL content plaatst, dus een NL applicatie/platform met NL clients. Dat zal voor veel overheidstoepassingen ook zo zijn, maar het is wel een context die niet altijd valide is.

Je schrijft ook over de ongewenste afwijking tussen aanleverde en geretourneerde formaat: als je vindt dat je server per se NL tz moet retourneren omdat dat hetzelfde zou zijn als dat wat je client instuurt, moet je dús ook afdwingen dat de client nl timezone gebruikt. Als een client vrij is om elke tijdzone te gebruiken en je server retourneert altijd NL tz heb je ook kan dat request en response niet in de zelfde tz zitten.

En ook belangrijk: een afwijking tussen aanleverde en geretourneerde formaat: speelt vooral bij POST/PUT request waarin de client in de response een representaties terugkrijgt van de resource die hij in zijn request heeft meegekregen. Een aantal belangrijke overwegingen hierbij:

• niet alle data (datetimes) die een client in zon request terugkrijgt, is door hemzelf in de request meegegeven. Server kunnen ook timestamps ed toevoegen aan de response
• veel data die client A ophaalt (GET) is door client B of een ander proces gecreëerd, niet door de client zelf.
  Ik denk dat het belangrijk is deze problematiek niet vanuit het simpele POST/PUT request-rewponse cycle te benaderen maar vanuit een platform perspectief waarin data door verschillende clients9en ook door andere processen) kan ontstaan we weer die veel andere clients opgehaald kan worden

[HenriKorver]

Hi @BvanRaaij, we zijn het bijna eens op alle punten maar ik vind het echt te ver gaan om in alle gevallen UTC in de responses te verplichten.

Ik probeer nog een ander voorbeeld te geven. Stel dat je een hele gebruikersvriendelijke API wil ontwikkelen waarbij de clients zelf kunnen aangeven in welke tijdzone ze de datetime gegevens terug willen krijgen van de API-provider (iets vergelijkbaars doen we al met CRS content negotiation voor geo-data, zie crs-negotiation). De huidige formulering van design rule /core/date-time/timezone maakt dit onmogelijk en remt ons in het ontwikkelen van gebruikersvriendelijke API's. Mijn voorstel is dus nog steeds om deze design rule te schrappen.

De eerste design rule /core/date-time/format zou genoeg moeten zijn voor 100% duidelijke interpretatie van datetime velden.

Trouwens heb ik ook nog (filosofische) twijfels over de derde design rule /core/date-time/date-omit-time-portion. Als je een API timezone proof wilt maken kun je het "tijd gedeelte" niet weglaten in datum velden. Immers door tijdszone-verschillen kan dezelfde datum op een andere dag vallen. Bijvoorbeeld iemand die is geboren in Engeland op zondag 2026-02-08T23:59:00+00:00 is vanuit NL perspectief geboren op maandag 2026-02-09T00:59:00+01:00.

[TimvdLippe]

@HenriKorver Als we ipv MUST een SHOULD maken, dan is die mogelijkheid er in uitzonderlijke gevallen wel. Zou de volgende formulering wel voldoende zijn voor jou?

APIs MUST accept any timezone offset in fields in requests containing a datetime. Fields in responses containing a datetime SHOULD be in UTC (e.g. Z as timezone offset).

[BvanRaaij]

Hi @HenriKorver leuk om samen tot betere ideeën te komen en ik waardeer je respons.
Tav je eerste punt: het idee om de client zelf de tijdzone te laten bepalen steun ik helemaal. Mijn vraag is waarom dat op de server moet gebeuren zoals jij voorstelt: je moet dan als client een tz als parameter in het request meegeven (die ook gevalideerd moet worden en met een 400 afgehandeld moet worden als het een foutieve tz-indicator is) om de datetime in de door de client gewenste tz terug te geven. Je kunt als client dan toch net zo goed de ontvangen datetime in Z lokaal converteren naar de door jou gewenste timezone? Dat scheelt een parameter incl fout-afhandeling en voor de client is het niet meer werk.

Tav je tweede punt (ook filosofisch ;-)): er zijn op elk moment van de dag 2 "huidige datums" op de wereld (op één ms na dan). Op dit moment is het hier 10-02-2026 maar is het in de laatste tijdzones voor de daggrens nog 9-02-2026 . Mijn punt tav deze rule is dat juist door timeportion toe te voegen aan velden waar we alleen datum bedoelen juist verwarring krijgen door ongewenste datumovergangen. Jouw voorbeeld klopt, maar de Engelsman die op 08-02-2026 geboren is, is overal op de wereld ook op die dag jarig. Ik denk dat ie ons redelijk voor gek verklaart als wij beweren dat ie toch echt op 9 februari jarig is. Dat is ook precies het verschil waar het om gaat: hebben we het over een datum of een tijdstip? Als het tijdstip relevant is (bijvoorbeeld omdat deze Engelse baby precies 3 uur na zijn geboorte een behandeling moet krijgen, dan is de time component relevant incl de tz conversie.). Als het om een datum gaat (en dat is heel vaak zo) bijvoorbeeld om te weten hoe oud iemand, per wanneer hij/zij meerderjarig is of AOW krijgt, kun je juist door het gebruik van time-componenten ongewenste datumverschuivingen krijgen.

SHOULD ipv MUST kan natuurlijk. Ik zou dan aanraden om wel een eis toe te voegen van motivering waarom men in een specifiek case afwijkt van het advies (@TimvdLippe ?)

[BvanRaaij]

Nog even een voorbeeld (uit mijn wereld (Agro en Food)) waaruit blijkt dat het onnodig gebruiken van datetimes in geval alleen dates nodig zijn verwarring oproept. Het CTGB bepaalt welke gewasbeschermingsmiddelen gebruikt mogen worden vanaf en tot wanneer. Het GTCB heeft een API ontwikkeld waarmee iedereen deze gegevens kan ophalen. Het screenshot een een stukje response van deze API:

In dit voorbeeld zie we een middel met:

• een toelatingsdatum ("authorisationStartDate" en niet "authorisationStartDateTime!") van 2018-19-04T22:00:00Z.
• een "expirationDate" van 2023-09-29T22:00:00Z
• een opgebruikdatum ("graceUsageDate") (datum tot wanneer bestaande voorraden mogen worden opgebruikt) van 2025-03-30T22:00:00Z
• een uiterste distributiedatum ("graceSaleDistrDate") (uiterste verkoopdatum) van 2024-03-30T23:00:00Z

Nou weet ik 100% zeker dat toelatingen vanaf een bepaalde datum tot een bepaalde datum lopen. Het is nauwelijks voorstelbaar dat een bepaald middel vanaf een bepaald tijdstip (22u 's avond in dit geval) ineens gebruikt mag worden en op de laatste dag tot 22u s avonds. En ja. als je op deze data tz-conversie naar de NL timezone toepast, kom je (niet toevallig) op hele dagen uit nl 2018-04-20, 2023-09-30, 2025-03-31 en 2024-03-31 (en in een aantal geval precies op de laatste dag van de maand, want toelatingen lopen altijd af na hele maanden) .

Ik vraag me dan af wat het toevoegen van tijden aan attributen die een datum voorstellen en waarin de tijdcomponent totaal irrelevant is oplevert, behalve heel veel verwarring. In dit geval MOET een client wel tz conversie doen, al ie dat niet doet kloppen zijn gegevens niet. Ik wil je de kost niet geven van het aantal clients dat deze conversie niet uitvoert maar de tijden er gewoon afhakt.
Kijk eens wat een verwarring er ontstaat rond het communicatie dan de 31e maart (2024 en 2025): één keer met 22:00:00 en één keer met 23:00:00 omdat de zomertijd in het ene jaar nog niet en in het andere jaar al wel was ingegaan op die datum.
(ik sla de discussie over gebrekkige naamgeving van attributen, waardoor het ook nog eens onduidelijk is of een expirationDate, graceUsageDate en graceSaleDistrDate nou "tot" of "tot-en-met" is maar even over hier)

Als we het clients makkelijk willen maken communiceer dan date formats als we dates bedoelen.

[HenriKorver]

@TimvdLippe Deal! Als MUST vervangen wordt door SHOULD dan ben ik akkoord.

[HenriKorver]

@BvanRaaij Bedankt voor je mooie voorbeeld uit de agro-food wereld. Je hebt me helemaal overtuigd, oftewel ik heb mijn filosofische twijfels over de derde design rule ingetrokken

[TimvdLippe]

Dank voor de feedback. Ik heb het geupdatet in 66a0af8 naar SHOULD.