DEV Community

Cover image for RESTful – Pílula 3 – Padrão de datas e horários em APIs REST
Anderson Contreira
Anderson Contreira

Posted on

RESTful – Pílula 3 – Padrão de datas e horários em APIs REST

#braziliandevs #development #rest #code

Datas e horários estão entre os tipos de dados mais problemáticos em APIs.
Diferenças de fuso horário, formatos inconsistentes e conversões erradas podem causar bugs difíceis de rastrear — pagamentos duplicados, relatórios incorretos, inconsistências em logs e muito mais.

Uma API RESTful madura deve usar um padrão consistente e universal.
O mais recomendado é o ISO 8601, que representa datas em um formato padronizado, legível e independente de localização.

Por que ISO 8601?

Porque o formato:

  • Evita ambiguidade entre regiões (ex.: 03/04 = 3 de abril? 4 de março?)
  • Representa fusos horários
  • É nativamente suportado pela maioria das linguagens
  • É adequado para bancos NoSQL, logs, integrações e auditorias

O formato padrão é assim:

YYYY-MM-DDTHH:mm:ssZ
Enter fullscreen mode Exit fullscreen mode

Exemplo real:

2025-11-06T19:30:00Z
Enter fullscreen mode Exit fullscreen mode
  • T separa a data da hora
  • Z indica que a hora está em UTC (Zero timezone)

Sempre use UTC

Em projetos internacionais (ou mesmo nacionais com horários de verão), trabalhar com horários locais rapidamente vira um caos.

A regra de ouro:

Armazene e trafegue tudo em UTC.
Apresente no fuso do usuário apenas na camada de visualização.

Exemplo usando UTC no payload:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2025-11-06T19:30:00Z",
  "updatedAt": "2025-11-09T02:15:45Z"
}
Enter fullscreen mode Exit fullscreen mode

Milissegundos e precisão

Alguns casos exigem granularidade maior.
Também é válido usar milissegundos:

2025-11-06T19:30:00.123Z
Enter fullscreen mode Exit fullscreen mode

Ou até microssegundos:

2025-11-06T19:30:00.123456Z
Enter fullscreen mode Exit fullscreen mode

Se sua API precisa de logs detalhados, auditoria ou rastreamento, isso pode ser importante.

Nunca use timestamps locais ou formatos regionais

❌ Exemplos ruins:

06/11/2025 19:30
11/06/2025 19:30
06-11-2025 19:30
2025/11/06 19:30
Enter fullscreen mode Exit fullscreen mode

Esses formatos quebram facilmente em ambientes diferentes e são interpretados de formas distintas dependendo da linguagem ou framework.

Combine consistência + clareza

Boas práticas:

  • Use ISO 8601 sempre
  • Armazene e envie datas em UTC
  • Inclua timezone explicitamente
  • Nomeie os campos com clareza (createdAt, updatedAt, deletedAt)
  • Use o mesmo formato em toda API

Resumo

  • Datas e horários são fonte comum de bugs em APIs
  • Use ISO 8601 com timezone
  • Trabalhe sempre em UTC
  • Fuja de formatos regionais
  • Mantenha consistência em todos os endpoints

Top comments (0)