Epoch, ISO 8601 o RFC 3339: ¿qué formato para una API?

Toda API que toca fechas termina teniendo que responder una pregunta: ¿cómo se ve realmente un campo de timestamp en el cable? Hay en realidad tres candidatos de uso habitual —un entero de epoch Unix en bruto, una cadena ISO 8601, y su prima más estricta RFC 3339. Todos describen el mismo instante en el tiempo, pero fallan de forma distinta cuando algo aguas abajo lo interpreta mal, y elegir el correcto desde el principio evita toda una categoría de reportes de error de «por qué esta fecha está desfasada unas horas» más adelante.

Qué es realmente cada formato

Un timestamp epoch Unix es un entero: el número de segundos (o milisegundos, o menos habitualmente microsegundos o nanosegundos) desde 1970-01-01T00:00:00Z, según la definición POSIX de time_t. No lleva zona horaria —siempre es relativo a UTC por construcción— pero tampoco lleva marcador de unidad, que es de donde viene la mayor parte de sus problemas reales.

ISO 8601 es el estándar internacional para representar fechas y horas como texto, y es deliberadamente amplio: permite fechas de calendario, fechas de numeración de semana, fechas ordinales, duraciones, intervalos, precisión reducida (solo un año, o un año y un mes), y valores de hora con o sin desfase UTC. Esa flexibilidad es exactamente lo que hace que «compatible con ISO 8601» sea una garantía más débil de lo que suena —dos sistemas pueden ser ambos técnicamente compatibles y aun así producir cadenas que el otro no puede analizar.

RFC 3339 es el perfil de internet del IETF de ISO 8601: mantiene exactamente una forma (YYYY-MM-DDTHH:MM:SS[.ffffff](Z|±HH:MM)) y elimina todo lo que ISO 8601 permite que haría ambiguo el análisis automático —sin fechas de semana, sin precisión reducida, y un desfase es obligatorio, nunca implícito. Cuando la gente dice «timestamp ISO 8601» en un contexto de API, lo que casi siempre quiere decir, y lo que casi siempre espera su código, es RFC 3339.

Dónde falla realmente cada uno

Los enteros epoch fallan en silencio, que es peor que fallar ruidosamente. 1700000000 es un número perfectamente válido tanto si significa segundos (14 de noviembre de 2023) como milisegundos (20 de enero de 1970) —una suposición de unidad equivocada no lanza un error, solo produce una fecha que está mal por órdenes de magnitud y parece plausible hasta que alguien lo nota. Este es el error de timestamp más común en sistemas que pasan valores epoch entre servicios escritos en lenguajes distintos, cada uno con su propia unidad predeterminada.

Las cadenas ISO 8601 simples fallan en el desfase. Una cadena como 2023-11-14T22:13:20 sin Z ni ±hh:mm es ISO 8601 válida pero genuinamente ambigua —¿es UTC, hora local del servidor, o la hora local del usuario de origen? Cada consumidor tiene que adivinar o consultar documentación fuera de banda, y distintos consumidores a veces adivinan de forma distinta.

RFC 3339 evita en gran parte ambos modos de fallo por construcción, por lo que es la recomendación predeterminada en las guías de estilo de API —el AIP-142 de Google, por ejemplo, lo exige para los campos de timestamp en APIs nuevas. Su caso límite restante es la precisión de fracción de segundo: la especificación permite cualquier número de dígitos tras el punto decimal, así que un productor que emite precisión de nanosegundo y un consumidor que trunca a milisegundo aún pueden discrepar sobre el instante exacto, solo que por un margen mucho más pequeño que un desajuste de unidad.

Elegir un formato para un campo nuevo

Para una API pública o entre servicios, opta por defecto por una cadena RFC 3339. Es legible en logs y depuradores en bruto sin decodificar, no es ambigua ni en la zona horaria ni en la precisión, y prácticamente cualquier biblioteca de fechas de lenguaje habitual la analiza y emite de forma nativa. El único coste son unos pocos bytes extra por valor comparado con un entero —irrelevante para casi cualquier payload de API.

Recurre a un entero epoch cuando el campo sea telemetría de alto volumen, un timestamp de métricas, o una clave interna de ordenación donde tanto el productor como el consumidor están bajo tu control y ya están de acuerdo en la unidad. Incluso entonces, documenta la unidad explícitamente en el nombre del campo (created_at_ms, no solo created_at) en lugar de confiar en la convención. Nuestra guía de timestamps Unix explicados cubre cómo funciona la detección de unidad basada en el número de dígitos cuando tienes que hacer ingeniería inversa de un campo epoch sin documentar.

La versión corta

Los enteros epoch son compactos pero no llevan unidad; el ISO 8601 simple es amplio pero puede omitir el desfase; RFC 3339 es la porción estrecha y no ambigua de ISO 8601 que la mayoría de las herramientas de API realmente esperan cuando dicen «fecha ISO». Si estás diseñando un campo nuevo y no tienes una razón de peso para optimizar el tamaño del payload, RFC 3339 elimina toda una categoría de errores de timestamp entre servicios antes de que puedan empezar.