Format de date recommandé pour l'API REST GET

105

Quel est le format d'horodatage recommandé pour une API REST GET comme celle-ci:

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

Je pense que le format de date réel devrait être le format ISO 8601, comme YYYY-MM-DDThh:mm:ssZpour l'heure UTC.

Devrions-nous utiliser la version ISO 8601 sans tirets ni deux-points, tels que:

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

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

http url rest date get Lorenzo Polidori
la source
Pourquoi le format ISO 8601 tel quel n'est pas une option pour vous?
Johannes
@Johannes le format ISO 8601 (dans la version sans traits d'union et deux-points) serait OK, je me demandais juste s'il existe une sorte d'approche recommandée pour représenter les dates dans les URL
Lorenzo Polidori

Réponses:

77

REST n'a pas de format de date recommandé. Cela se résume vraiment à ce qui fonctionne le mieux pour votre utilisateur final et votre système. Personnellement, je voudrais m'en tenir à une norme comme celle que vous avez pour ISO 8601 (encodée en url).

Si ne pas avoir URI laid est une préoccupation (par exemple , ne comprenant pas l'URL de la version codée :, -, en vous URI) et (humain) est adressabilité pas aussi important, vous pouvez aussi considérer le temps d'époque (par exemple http://example.com/start/1331162374). L'URL semble un peu plus propre, mais vous perdez certainement la lisibilité.

C'est /2012/03/07un autre format que vous voyez beaucoup. Vous pourriez développer cela, je suppose. Si vous suivez cette voie, assurez-vous simplement que vous êtes toujours à l'heure GMT (et indiquez-le clairement dans votre documentation) ou vous voudrez peut-être également inclure une sorte d'indicateur de fuseau horaire.

En fin de compte, cela se résume à ce qui fonctionne pour votre API et votre utilisateur final. Votre API devrait fonctionner pour vous, pas pour vous ;-).

bonne
la source
12
Merci, réponse très utile. Je pense que je vais opter pour la version compressée d'ISO 8601 (c'est-à-dire http://api.example.com/start_date/YYYYMMDDThhmmssZ) qui est bonne pour la lisibilité et les URL propres.
Lorenzo Polidori
7
Mais JSON n'ont un format de date recommandée et il est ISO 8601 :)
Radu Potop
@stalemate Les objets Date par défaut sont sérialisés sous la forme d'une chaîne contenant la date au format ISO. developer.mozilla.org/en-US/docs/JSON
Radu Potop
5
@RaduPotop Oui, mais il s'agit des standards HTTP et URI dont nous parlons. Je ne suis pas sûr de ce que JSON a à voir avec cela.
nategood
3
Je veux juste noter que les tirets n'ont pas besoin d'être encodés en URL.
user128216
97

Consultez cet article pour les 5 lois des dates et heures API ICI :

  • Loi n ° 1: utilisez ISO-8601 pour vos dates
  • Loi n ° 2: Acceptez n'importe quel fuseau horaire
  • Loi n ° 3: le stocker en UTC
  • Loi n ° 4: le renvoyer en UTC
  • Loi n ° 5: n'utilisez pas le temps si vous n'en avez pas besoin

Plus d'informations dans la documentation.

mohamed-ibrahim
la source
2
-1, car ce 2017-11-20T11%3A00%3A00Zn'est tout simplement pas très lisible. De plus (spécifique à IIS), il semble être très paranoïaque à propos des deux-points dans les URL, même s'ils sont encodés.
Iain
2
Ce lien - agiletribe.wordpress.com/2015/06/10/jsonrest-api-handling-dates recommande une époque entière pour éviter les problèmes de lisibilité humaine qui pourraient être rencontrés avec le format iso-8601. Faites-moi savoir si vous avez des points de vue différents.
Andy Dufresne
5
Notez que les traits d'union et les points ne sont pas des caractères réservés dans les URL. Seuls les deux points nécessitent un encodage URL ( en.wikipedia.org/wiki/Percent-encoding ). Dans ISO-8601 ( en.wikipedia.org/wiki/ISO_8601 ), les tirets sont obligatoires mais les deux-points sont facultatifs. Les variantes ISO-8601 correctes à utiliser dans les URL sont donc AAAA-MM-JJThhmmssZ et AAAA-MM-JJThhmmss.mmmZ si vous avez besoin d'une plus grande précision.
Bruce Adams
Un article fréquemment lié et fortement débattu. Bien que je sois d'accord avec le choix d'un format triable s'il doit s'agir d'une chaîne , un horodatage unix (que l'article ne reconnaît même pas) a chacun des avantages énoncés et plus encore. Jusqu'à la présentation, les questions de fuseaux horaires et d'heure d'été (et de décisions politiques) n'existent même pas.
kaay
18

RFC6690 - Format de lien des environnements RESTful contraints (CoRE) N'indique pas explicitement quel format de date devrait être cependant dans la section 2. Format de lien il pointe vers RFC 3986. Cela implique que la recommandation pour le type de date dans la RFC 3986 doit être utilisée.

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

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

ce que cela se résume à: AAAA-MM-jjTHH: mm: ss.ss ± hh: mm

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

Est le pari le plus sûr.

Matas Vaitkevicius
la source
12

Chaque champ datetime en entrée / sortie doit être au format UNIX / epoch . Cela évite la confusion entre les développeurs de différents côtés de l'API.

Avantages:

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

Les inconvénients:

  • Traitement supplémentaire pour la conversion en UTC pour le stockage au format UTC dans la base de données.
  • Lisibilité des entrées / sorties.
  • Lisibilité des URL GET.

Remarques:

  • Les fuseaux horaires sont un problème de couche de présentation! La plupart de votre code ne devrait pas traiter de fuseaux horaires ou d'heure locale, il devrait passer l'heure Unix.
  • Si vous voulez stocker une heure lisible par l'homme (par exemple des journaux), envisagez de la stocker avec l'heure Unix, pas à la place de l'heure Unix.
Mithun Sreedharan
la source
1
Je ne pourrais pas être plus d'accord.
Jorge.V
1
La seule chose que j'ajouterais à cela est de considérer dès le départ si vous devrez prendre en compte les millisecondes n'importe où dans votre système. Si tel est le cas, utilisez la version milliseconde de l'horodatage Unix.
jamesjansson