Formato de data recomendado para REST GET API

105

Qual é o formato de carimbo de data / hora recomendado para uma API REST GET como este:

http://api.example.com/start_date/{timestamp}

Acho que o formato de data real deve ser o formato ISO 8601, como YYYY-MM-DDThh:mm:ssZpara a hora UTC.

Devemos usar a versão ISO 8601 sem hifens e dois pontos, como:

http://api.example.com/start_date/YYYYMMDDThhmmssZ

ou devemos codificar o formato ISO 8601, usando, por exemplo, a codificação base64?

Lorenzo Polidori
fonte
Por que o formato ISO 8601 não é uma opção para você?
Johannes
@Johannes, o formato ISO 8601 (na versão sem hífens e dois-pontos) estaria OK, eu estava apenas me perguntando se existe uma espécie de abordagem recomendada para representar datas em URLs
Lorenzo Polidori

Respostas:

77

REST não tem um formato de data recomendado. Na verdade, tudo se resume ao que funciona melhor para o usuário final e o sistema. Pessoalmente, gostaria de seguir um padrão como o que você tem para ISO 8601 (codificado por url).

Se não ter feio URI é uma preocupação (por exemplo, não incluindo a versão codificada url :, -, em que você URI) e endereçamento (humana) não é tão importante, você também pode considerar tempo de época (por exemplo http://example.com/start/1331162374). O URL parece um pouco mais limpo, mas você certamente perde a legibilidade.

Esse /2012/03/07é outro formato que você vê muito. Você poderia expandir isso, suponho. Se você seguir esse caminho, certifique-se de estar sempre no horário GMT (e deixe isso claro em sua documentação) ou talvez queira incluir algum tipo de indicador de fuso horário.

Em última análise, tudo se resume ao que funciona para sua API e seu usuário final. Sua API deve funcionar para você, não para ela ;-).

nategood
fonte
12
Obrigado, resposta muito útil. Acho que optarei pela versão compactada do ISO 8601 (ou seja http://api.example.com/start_date/YYYYMMDDThhmmssZ), que é boa para legibilidade e URLs limpos.
Lorenzo Polidori
7
Mas JSON faz ter um formato de data recomendada e é ISO 8601 :)
Radu Potop
@stalemate Objetos de data por padrão serializam como uma string contendo a data no formato ISO. developer.mozilla.org/en-US/docs/JSON
Radu Potop
5
@RaduPotop Sim, mas estamos falando dos padrões HTTP e URI. Não tenho certeza do que JSON tem a ver com isso.
nategood
3
Só quero observar que os hifens não precisam ser codificados por URL.
user128216
97

Verifique este artigo para as 5 leis de datas e horários da API AQUI :

  • Lei nº 1: Use ISO-8601 para suas datas
  • Lei # 2: Aceite qualquer fuso horário
  • Lei # 3: Armazene em UTC
  • Lei # 4: Devolva em UTC
  • Lei nº 5: Não use o tempo se não precisar dele

Mais informações nos documentos.

Mohamed-Ibrahim
fonte
2
-1, pois 2017-11-20T11%3A00%3A00Znão é muito legível. Além disso (específico do IIS), parece ser muito paranóico sobre os dois pontos em URLs, mesmo se eles estiverem codificados.
Iain de
2
Este link - agiletribe.wordpress.com/2015/06/10/jsonrest-api-handling-dates recomenda a época inteira para evitar problemas de legibilidade humana que podem ocorrer com o formato iso-8601. Deixe-me saber se você tem diferentes pontos de vista.
Andy Dufresne
5
Observe que hífens e pontos não são caracteres reservados em URLs. Apenas os dois pontos requerem codificação de URL ( en.wikipedia.org/wiki/Percent-encoding ). Em ISO-8601 ( en.wikipedia.org/wiki/ISO_8601 ), os hifens são obrigatórios, mas os dois pontos são opcionais. Portanto, as variantes de ISO-8601 corretas para usar em URLs são AAAA-MM-DDThhmmssZ e AAAA-MM-DDThhmmss.mmmZ se você precisar de maior precisão.
Bruce Adams
Um artigo frequentemente vinculado e muito debatido. Embora eu concorde com a escolha de um formato classificável, se for uma string , um carimbo de data / hora Unix (que o artigo nem mesmo reconhece) tem todos os benefícios declarados e mais. Até a apresentação, as questões de fuso horário e horário de verão (e decisões políticas) nem mesmo existem.
kaay
18

RFC6690 - Formato de link de ambientes RESTful restritos (CoRE) Não declara explicitamente qual formato de data deve ser, no entanto, na seção 2. Formato de link, ele aponta para RFC 3986. Isso implica que a recomendação para o tipo de data no RFC 3986 deve ser usada.

Basicamente, Data e Hora RFC 3339 na Internet é o documento a ser examinado que diz:

formato de data e hora para uso em protocolos da Internet que é um perfil do padrão ISO 8601 para representação de datas e horas usando o calendário gregoriano.

o que isso se resume a: AAAA-MM-ddTHH: mm: ss.ss ± hh: mm

(por exemplo, 1937-01-01T12: 00: 27.87 + 00: 20)

É a aposta mais segura.

Matas Vaitkevicius
fonte
12

Cada campo de data e hora na entrada / saída precisa estar no formato UNIX / época . Isso evita a confusão entre os desenvolvedores em diferentes lados da API.

Prós:

  • O formato de época não tem fuso horário.
  • A época tem um único formato (a hora Unix é um único número assinado).
  • A hora da época não é afetada pelo horário de verão.
  • A maioria das estruturas de back-end e todas as APIs ios / android nativas oferecem suporte à conversão de época.
  • A parte da conversão de horário local pode ser feita inteiramente no lado do aplicativo, dependendo da configuração de fuso horário do dispositivo / navegador do usuário.

Contras:

  • Processamento extra para conversão em UTC para armazenamento em formato UTC no banco de dados.
  • Legibilidade de entrada / saída.
  • Legibilidade de URLs GET.

Notas:

  • Os fusos horários são um problema da camada de apresentação! A maior parte do seu código não deve estar lidando com fusos horários ou hora local, deve estar passando o tempo do Unix.
  • Se você deseja armazenar um horário legível por humanos (por exemplo, logs), considere armazená-lo junto com o horário Unix, não em vez do horário Unix.
Mithun Sreedharan
fonte
1
Não poderia concordar mais.
Jorge.V
1
A única coisa que eu adicionaria a isso é considerar desde o início se você precisará considerar os milissegundos em qualquer lugar do seu sistema. Em caso afirmativo, use a versão em milissegundos do carimbo de data / hora Unix.
Jamesjansson de
1

Sempre use UTC:

Por exemplo, eu tenho um componente de programação que leva em um parâmetro DATETIME. Quando eu chamo isso usando um verbo GET, uso o seguinte formato, em que o nome do meu parâmetro de entrada é scheduleDate.

Exemplo:
https: // localhost / api / getScheduleForDate? ScheduleDate = 2003-11-21T01: 11: 11Z

Michael K
fonte