Timestamps dans les APIs REST

Les formats courants

• Unix secondes : compact, simple pour les comparaisons et les filtres.
• Unix millisecondes : naturel pour JavaScript, plus précis.
• ISO 8601 : lisible, explicite, souvent préféré dans les APIs publiques modernes.

Nommage des champs

Un champ created_at ne dit pas si la valeur est une chaîne ISO, des secondes ou des millisecondes. Si vous utilisez des entiers, documentez l'unité dans le schéma OpenAPI ou utilisez un nom explicite comme created_at_unix ou created_at_ms.

Webhooks

Les signatures de webhooks incluent souvent un timestamp pour limiter les attaques par rejeu. Le serveur receveur doit comparer ce timestamp à son horloge et refuser les messages trop anciens.

const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - webhookTimestamp) > 300) {
  throw new Error('Webhook trop ancien');
}

Rate limit et pagination

Les headers de rate limit comme X-RateLimit-Reset contiennent fréquemment un timestamp Unix en secondes. Certaines APIs utilisent aussi un timestamp comme curseur temporel pour paginer des logs, messages ou événements.

Recommandations

• Choisissez un format principal et tenez-vous-y.
• Acceptez ISO 8601 en entrée si l'API est publique.
• Retournez éventuellement l'ISO en plus du timestamp pour faciliter le débogage.
• Utilisez des entiers 64 bits pour éviter les limites 2038 et supporter les millisecondes.

Questions fréquentes