Format de date recommandé pour une API REST GET

Question

Quel est le format de timestamp recommandé pour une API REST GET comme celle-ci :

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

Je pense que le format de date actuel devrait être le format ISO 8601, tel que YYYY-MM-DDThh:mm:ssZ pour l'heure UTC.

Devrions-nous utiliser la version ISO 8601 sans tirets et deux-points, comme :

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

ou devrions-nous encoder le format ISO 8601, en utilisant par exemple un encodage base64 ?

Answer 1

Vérifiez cet article pour les 5 lois des dates et heures des API ICI:

• Loi n°1 : Utilisez l'ISO-8601 pour vos dates
• Loi n°2 : Acceptez n'importe quel fuseau horaire
• Loi n°3 : Stockez-le en UTC
• Loi n°4 : Renvoyez-le en UTC
• Loi n°5 : Ne pas utiliser l'heure si vous n'en avez pas besoin

Plus d'informations dans la documentation.

Answer 2

REST n'a pas de format de date recommandé. En réalité, cela dépend de ce qui fonctionne le mieux pour votre utilisateur final et votre système. Personnellement, je préférerais m'en tenir à une norme comme celle de l'ISO 8601 (encodée en URL).

Si ne pas avoir une URI laide est une préoccupation (par exemple, ne pas inclure la version encodée en URL de :, -, dans votre URI) et que l'adressabilité (humaine) n'est pas aussi importante, vous pourriez également envisager l'heure epoch (par exemple, http://example.com/start/1331162374). L'URL semble un peu plus propre, mais vous perdez certainement en lisibilité.

Le /2012/03/07 est un autre format que l'on voit souvent. Vous pourriez l'élargir, je suppose. Si vous décidez d'adopter cette approche, assurez-vous d'être toujours en temps GMT (et précisez-le dans votre documentation) ou vous voudrez peut-être également inclure un indicateur de fuseau horaire.

En fin de compte, cela dépend de ce qui fonctionne pour votre API et votre utilisateur final. Votre API devrait fonctionner pour vous, et non l'inverse ;-).

Answer 3

Chaque champ datetime en entrée/sortie doit être au format UNIX/epoch. Cela évite la confusion entre les développeurs des différentes parties de l'API.

Avantages :

• Le format Epoch n'a pas de fuseau horaire.
• L'Epoch a un seul format (le temps Unix est un nombre signé unique).
• Le temps Epoch n'est pas affecté par le passage à l'heure d'été.
• La plupart des frameworks Backend et toutes les API native ios/android prennent en charge la conversion en epoch.
• La conversion en heure locale peut être entièrement réalisée du côté de l'application en fonction du paramétrage de fuseau horaire de l'appareil/navigateur de l'utilisateur.

Inconvénients :

• Traitement supplémentaire pour la conversion en UTC afin de stocker au format UTC dans la base de données.
• Lisibilité de l'entrée/sortie.
• Lisibilité des URLs GET.

Notes :

• Les fuseaux horaires sont un problème de couche de présentation ! La plupart de votre code ne devrait pas manipuler les fuseaux horaires ou l'heure locale, il devrait simplement transmettre l'heure Unix.
• Si vous souhaitez stocker une heure lisible par les humains (par exemple des journaux), envisagez de le faire en parallèle avec le temps Unix, et non à la place du temps Unix.

Answer 4

RFC6690 - Formats de liens Constrained RESTful Environments (CoRE) ne précise pas explicitement le format de date à utiliser, cependant dans la section 2. Format de lien, il renvoie au RFC 3986. Cela implique que la recommandation pour le type de date dans le RFC 3986 devrait être utilisée.

Essentiellement, RFC 3339 Date et heure sur Internet est le document à consulter qui dit :

format de date et heure à utiliser dans les protocoles Internet qui est un profil de la norme ISO 8601 pour la représentation des dates et heures utilisant le calendrier grégorien.

ce qui se résume ainsi : YYYY-MM-ddTHH:mm:ss.ss±hh:mm

(par exemple 1937-01-01T12:00:27.87+00:20)

est le choix le plus sûr.

Answer 5

Toujours utiliser UTC :

Par exemple, j'ai un composant d'horaire qui prend un paramètre DATETIME. Lorsque j'appelle ceci en utilisant un verbe GET, j'utilise le format suivant où mon nom de paramètre entrant est scheduleDate.

Exemple:
https://localhost/api/getScheduleForDate?scheduleDate=2003-11-21T01:11:11Z