Formato de fecha recomendado para REST GET API

105

¿Cuál es el formato de marca de tiempo recomendado para una API REST GET como esta?

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

Creo que el formato de fecha real debería ser el formato ISO 8601, como la YYYY-MM-DDThh:mm:ssZhora UTC.

¿Deberíamos utilizar la versión ISO 8601 sin guiones ni dos puntos, como:

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

¿O deberíamos codificar el formato ISO 8601, usando, por ejemplo, codificación base64?

http url rest date get Lorenzo Polidori
fuente
¿Por qué el formato ISO 8601 no es una opción para usted?
Johannes
@Johannes, el formato ISO 8601 (en la versión sin guiones y dos puntos) estaría bien, solo me preguntaba si hay algún tipo de enfoque recomendado para representar fechas en URL
Lorenzo Polidori

Respuestas:

77

REST no tiene un formato de fecha recomendado. Realmente se reduce a lo que funciona mejor para su usuario final y su sistema. Personalmente, me gustaría ceñirme a un estándar como el que tiene para ISO 8601 (codificado en URL).

Si no teniendo fea URI es una preocupación (por ejemplo, sin incluir la versión codificada de la URL :, -, en la que URI) y la capacidad de direccionamiento (humana) no es tan importante, también se puede considerar el tiempo época (por ejemplo http://example.com/start/1331162374). La URL se ve un poco más limpia, pero ciertamente pierde legibilidad.

El /2012/03/07es otro formato que se ve mucho. Supongo que podrías ampliar eso. Si sigue esta ruta, asegúrese de estar siempre en la hora GMT (y deje eso claro en su documentación) o también puede incluir algún tipo de indicador de zona horaria.

En última instancia, se reduce a lo que funciona para su API y su usuario final. Tu API debería funcionar para ti, no para ti ;-).

nategood
fuente
12
Gracias, respuesta muy útil. Creo que optaré por la versión comprimida de ISO 8601 (es decir http://api.example.com/start_date/YYYYMMDDThhmmssZ) que es buena para la legibilidad y las URL limpias.
Lorenzo Polidori
7
Pero JSON hace tener un formato de fecha recomendada y es la norma ISO 8601 :)
Radu Potop
@stalemate Los objetos de fecha se serializan de forma predeterminada como una cadena que contiene la fecha en formato ISO. developer.mozilla.org/en-US/docs/JSON
Radu Potop
5
@RaduPotop Sí, pero estamos hablando de los estándares HTTP y URI. No estoy seguro de qué tiene que ver JSON con eso.
nategood
3
Solo quiero señalar que los guiones no necesitan estar codificados en URL.
user128216
97

Consulte este artículo para conocer las 5 leyes de fechas y horarios de API AQUÍ :

  • Ley n. ° 1: use ISO-8601 para sus fechas
  • Ley n. ° 2: acepta cualquier zona horaria
  • Ley # 3: Guárdelo en UTC
  • Ley # 4: Devuélvalo en UTC
  • Ley # 5: No use el tiempo si no lo necesita

Más información en los documentos.

mohamed-ibrahim
fuente
2
-1, ya 2017-11-20T11%3A00%3A00Zque no es muy legible. Además (específico de IIS) parece ser muy paranoico acerca de los dos puntos en las URL, incluso si están codificadas.
Iain
2
Este enlace, agiletribe.wordpress.com/2015/06/10/jsonrest-api-handling-dates, recomienda integer epoch para evitar problemas de legibilidad humana que podrían experimentarse con el formato iso-8601. Avísame si tienes diferentes puntos de vista.
Andy Dufresne
5
Tenga en cuenta que los guiones y los puntos no son caracteres reservados en las URL. Solo los dos puntos requieren codificación de URL ( en.wikipedia.org/wiki/Percent-encoding ). En ISO-8601 ( en.wikipedia.org/wiki/ISO_8601 ) los guiones son obligatorios pero los dos puntos son opcionales. Por lo tanto, las variantes correctas de ISO-8601 para usar en las URL son YYYY-MM-DDThhmmssZ y YYYY-MM-DDThhmmss.mmmZ si necesita una mayor precisión.
Bruce Adams
Un artículo frecuentemente vinculado y muy debatido. Si bien estoy de acuerdo con la elección de un formato ordenable si debe ser una cadena , una marca de tiempo de Unix (que el artículo ni siquiera reconoce) tiene todos los beneficios declarados y más. Hasta la presentación, los problemas de las zonas horarias y el horario de verano (y las decisiones políticas) ni siquiera existen.
kaay
18

RFC6690 - Formato de enlace de entornos RESTful restringidos (CoRE) No indica explícitamente qué formato de fecha debería ser, sin embargo, en la sección 2. Formato de enlace apunta a RFC 3986. Esto implica que se debe utilizar la recomendación para el tipo de fecha en RFC 3986 .

Básicamente, RFC 3339 Date and Time en Internet es el documento que hay que mirar que dice:

formato de fecha y hora para usar en protocolos de Internet que es un perfil de la norma ISO 8601 para la representación de fechas y horas usando el calendario gregoriano.

a qué se reduce esto: AAAA-MM-ddTHH: mm: ss.ss ± hh: mm

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

Es la apuesta más segura.

Matas Vaitkevicius
fuente
12

Cada campo de fecha y hora de entrada / salida debe estar en formato UNIX / epoch . Esto evita la confusión entre desarrolladores en diferentes lados de la API.

Pros:

  • El formato Epoch no tiene zona horaria.
  • Epoch tiene un formato único (la hora Unix es un número con una sola firma).
  • El horario de verano no se ve afectado por el horario de verano.
  • La mayoría de los marcos de backend y todas las API nativas de ios / android admiten la conversión de época.
  • La parte de conversión de la hora local se puede realizar completamente en el lado de la aplicación, dependiendo de la configuración de la zona horaria del dispositivo / navegador del usuario.

Contras:

  • Procesamiento adicional para convertir a UTC para almacenar en formato UTC en la base de datos.
  • Legibilidad de entrada / salida.
  • Legibilidad de las URL GET.

Notas:

  • ¡Las zonas horarias son un problema de la capa de presentación!La mayor parte de su código no debería tratar con zonas horarias o la hora local, debería estar pasando la hora de Unix.
  • Si desea almacenar una hora legible por humanos (por ejemplo, registros), considere almacenarla junto con la hora Unix, no en lugar de la hora Unix.
Mithun Sreedharan
fuente
1
No podría estar más de acuerdo.
Jorge.V
1
Lo único que agregaría a esto es considerar desde el principio si necesitará considerar milisegundos en cualquier parte de su sistema. Si es así, use la versión en milisegundos de la marca de tiempo de Unix.
jamesjansson