Epoch, ISO 8601 oder RFC 3339: welches Format für eine API?

Jede API, die mit Daten arbeitet, muss irgendwann eine Frage beantworten: Wie sieht ein Zeitstempelfeld auf der Leitung tatsächlich aus? Es gibt in der Praxis drei gängige Kandidaten — eine rohe Unix-Epoch-Ganzzahl, einen ISO-8601-String und dessen strengeren Verwandten RFC 3339. Alle beschreiben denselben Zeitpunkt, doch sie scheitern unterschiedlich, wenn etwas nachgelagert falsch damit umgeht, und die richtige Wahl von Anfang an vermeidet eine ganze Kategorie späterer “Warum ist dieses Datum um ein paar Stunden versetzt”-Bugreports.

Was jedes Format tatsächlich ist

Ein Unix-Epoch-Zeitstempel ist eine Ganzzahl: die Anzahl der Sekunden (oder Millisekunden, seltener Mikro- oder Nanosekunden) seit 1970-01-01T00:00:00Z, nach POSIX-Definition von time_t. Er trägt keine Zeitzone — er ist konstruktionsbedingt immer relativ zu UTC —, trägt aber auch keinen Einheitsmarker, was die Quelle der meisten realen Probleme ist.

ISO 8601ist der internationale Standard zur textuellen Darstellung von Datum und Uhrzeit und bewusst breit gefasst: Er erlaubt Kalenderdaten, Wochennummerierungs- Daten, Ordinaldaten, Zeitspannen, Intervalle, reduzierte Genauigkeit (nur ein Jahr, oder Jahr und Monat) und Zeitwerte mit oder ohne UTC-Offset. Genau diese Flexibilität macht “ISO-8601-konform” zu einer schwächeren Garantie, als es klingt — zwei Systeme können beide technisch konform sein und trotzdem Strings erzeugen, die das jeweils andere nicht parsen kann.

RFC 3339 ist das internetseitige Profil von ISO 8601 der IETF: Es behält genau eine Form (YYYY-MM-DDTHH:MM:SS[.ffffff](Z|±HH:MM)) und lässt alles weg, was ISO 8601 erlaubt, was automatisches Parsen mehrdeutig machen würde — keine Wochendaten, keine reduzierte Genauigkeit, und ein Offset ist Pflicht, nie implizit. Wenn Menschen in einem API-Kontext von “ISO-8601-Zeitstempel” sprechen, meinen sie fast immer, und ihr Code erwartet fast immer, RFC 3339.

Wo jedes Format tatsächlich scheitert

Epoch-Ganzzahlen scheitern still, was schlimmer ist als laut zu scheitern. 1700000000ist eine völlig gültige Zahl, egal ob sie Sekunden (14. November 2023) oder Millisekunden (20. Januar 1970) bedeutet — eine falsche Einheitsannahme wirft keinen Fehler, sie erzeugt einfach ein um Größenordnungen falsches Datum, das plausibel aussieht, bis es jemand bemerkt. Das ist der mit Abstand häufigste Zeitstempel-Bug in Systemen, die Epoch-Werte zwischen in verschiedenen Sprachen geschriebenen Diensten austauschen, jeder mit seiner eigenen Standardeinheit.

Einfache ISO-8601-Strings scheitern beim Offset. Ein String wie 2023-11-14T22:13:20 ohne Z oder ±hh:mmist gültiges ISO 8601, aber wirklich mehrdeutig — ist es UTC, lokale Serverzeit oder die lokale Zeit der Nutzerin oder des Nutzers, von dem es stammt? Jeder Konsument muss raten oder außerhalb der eigentlichen Daten Dokumentation konsultieren, und unterschiedliche Konsumenten raten manchmal unterschiedlich.

RFC 3339 vermeidet beide Fehlerarten konstruktionsbedingt größtenteils, weshalb es die Standardempfehlung in API-Styleguides ist — Googles AIP-142 schreibt es etwa für Zeitstempelfelder in neuen APIs vor. Der verbleibende Grenzfall ist die Präzision der Sekundenbruchteile: Die Spezifikation erlaubt beliebig viele Nachkommastellen, sodass eine Quelle mit Nanosekundengenauigkeit und ein Konsument, der auf Millisekunden kürzt, sich beim genauen Zeitpunkt trotzdem uneinig sein können, nur um eine viel kleinere Spanne als bei einer Einheitenverwechslung.

Ein Format für ein neues Feld wählen

Für eine öffentliche oder dienstübergreifende API greifen Sie standardmäßig zu einem RFC-3339-String. Er ist in rohen Logs und Debuggern ohne Dekodierung lesbar, er ist bei Zeitzone und Genauigkeit eindeutig, und praktisch jede Datumsbibliothek jeder gängigen Sprache parst und erzeugt ihn nativ. Der einzige Preis sind ein paar zusätzliche Bytes pro Wert im Vergleich zu einer Ganzzahl — für fast jede API-Nutzlast irrelevant.

Greifen Sie zu einer Epoch-Ganzzahl, wenn das Feld hochvolumige Telemetrie, ein Metrik-Zeitstempel oder ein interner Sortier-/Ordnungsschlüssel ist, bei dem jede Quelle und jeder Konsument unter Ihrer eigenen Kontrolle stehen und sich bereits auf die Einheit geeinigt haben. Selbst dann dokumentieren Sie die Einheit explizit im Feldnamen (created_at_ms, nicht nur created_at), statt sich auf Konvention zu verlassen. Unser Ratgeber Unix-Zeitstempel erklärt behandelt, wie die Einheitenerkennung anhand der Ziffernanzahl funktioniert, wenn Sie ein undokumentiertes Epoch-Feld zurückentwickeln müssen.

Die Kurzfassung

Epoch-Ganzzahlen sind kompakt, tragen aber keine Einheit; einfaches ISO 8601 ist breit gefasst, kann aber den Offset weglassen; RFC 3339 ist die schmale, eindeutige Teilmenge von ISO 8601, die die meisten API-Werkzeuge tatsächlich erwarten, wenn sie von “ISO-Datum” sprechen. Entwerfen Sie ein neues Feld und haben keinen starken Grund, auf Nutzlastgröße zu optimieren, entfernt RFC 3339 eine ganze Kategorie dienstübergreifender Zeitstempel-Bugs, bevor sie entstehen kann.