Empfohlenes Datumsformat für die REST GET API

105

Was ist das empfohlene Zeitstempelformat für eine REST GET-API wie diese:

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

Ich denke, das tatsächliche Datumsformat sollte das ISO 8601-Format sein, beispielsweise YYYY-MM-DDThh:mm:ssZfür die UTC-Zeit.

Sollten wir die ISO 8601-Version ohne Bindestriche und Doppelpunkte verwenden, wie z.

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

oder sollten wir das ISO 8601-Format codieren, zum Beispiel mit Base64-Codierung?

http url rest date get Lorenzo Polidori
quelle
Warum ist das ISO 8601-Format nicht so wie es ist eine Option für Sie?
Johannes
@Johannes das ISO 8601-Format (in der Version ohne Bindestriche und Doppelpunkte) wäre in Ordnung, ich habe mich nur gefragt, ob es einen empfohlenen Ansatz für die Darstellung von Daten in URLs gibt
Lorenzo Polidori

Antworten:

76

REST hat kein empfohlenes Datumsformat. Es läuft wirklich darauf hinaus, was für Ihren Endbenutzer und Ihr System am besten funktioniert. Persönlich möchte ich mich an einen Standard halten, wie Sie ihn für ISO 8601 (URL-codiert) haben.

Wenn nicht mit hässlichen URI ein Anliegen ist (zB nicht mit der URL codierten Version von :, -, in Sie URI) und (human) Adressierbarkeit ist nicht so wichtig, könnten Sie auch Epoche Zeit (zB betrachten http://example.com/start/1331162374). Die URL sieht etwas sauberer aus, aber Sie verlieren sicherlich die Lesbarkeit.

Das /2012/03/07ist ein anderes Format, das Sie oft sehen. Sie könnten das erweitern, nehme ich an. Wenn Sie diesen Weg gehen, stellen Sie einfach sicher, dass Sie entweder immer in GMT-Zeit sind (und machen Sie dies in Ihrer Dokumentation deutlich), oder Sie möchten möglicherweise auch eine Art Zeitzonenindikator einfügen.

Letztendlich läuft es darauf hinaus, was für Ihre API und Ihren Endbenutzer funktioniert. Deine API sollte für dich funktionieren, nicht du dafür ;-).

nategood
quelle
12
Danke, sehr nützliche Antwort. Ich denke, ich werde mich für die komprimierte Version von ISO 8601 (dh http://api.example.com/start_date/YYYYMMDDThhmmssZ) entscheiden, die gut für die Lesbarkeit und saubere URLs ist.
Lorenzo Polidori
7
Aber JSON hat ein empfohlenes Datumsformat und es ist ISO 8601 :)
Radu Potop
@stalemate Datumsobjekte werden standardmäßig als Zeichenfolge serialisiert, die das Datum im ISO-Format enthält. developer.mozilla.org/en-US/docs/JSON
Radu Potop
5
@RaduPotop Ja, aber das sind HTTP- und URI-Standards, über die wir sprechen. Ich bin mir nicht sicher, was JSON damit zu tun hat.
Nategood
3
Ich möchte nur darauf hinweisen, dass Bindestriche nicht URL-codiert sein müssen.
user128216
96

In diesem Artikel finden Sie HIER die 5 Gesetze zu API-Daten und -Zeiten :

  • Gesetz Nr. 1: Verwenden Sie ISO-8601 für Ihre Daten
  • Gesetz Nr. 2: Akzeptiere jede Zeitzone
  • Gesetz 3: Speichern Sie es in UTC
  • Gesetz Nr. 4: Geben Sie es in UTC zurück
  • Gesetz Nr. 5: Nutze keine Zeit, wenn du sie nicht brauchst

Weitere Infos in den Dokumenten.

mohamed-ibrahim
quelle
2
-1, da 2017-11-20T11%3A00%3A00Zes einfach nicht sehr lesbar ist. Außerdem (IIS-spezifisch) scheint es sehr paranoid zu sein, Doppelpunkte in URLs zu verwenden, selbst wenn sie codiert sind.
Iain
2
Dieser Link - agiletribe.wordpress.com/2015/06/10/jsonrest-api-handling-dates empfiehlt eine ganzzahlige Epoche, um Probleme mit der menschlichen Lesbarkeit zu vermeiden, die beim ISO-8601-Format auftreten können. Lassen Sie mich wissen, wenn Sie unterschiedliche Ansichten haben.
Andy Dufresne
5
Beachten Sie, dass Bindestriche und Punkte keine reservierten Zeichen in URLs sind. Nur die Doppelpunkte erfordern eine URL-Codierung ( en.wikipedia.org/wiki/Percent-encoding ). In ISO-8601 ( en.wikipedia.org/wiki/ISO_8601 ) sind die Bindestriche erforderlich, die Doppelpunkte sind jedoch optional. Die richtigen ISO-8601-Varianten für die Verwendung in URLs sind also JJJJ-MM-TTThhmmssZ und JJJJ-MM-TTThhmmss.mmmZ, wenn Sie eine höhere Genauigkeit benötigen.
Bruce Adams
Ein häufig verlinkter und stark diskutierter Artikel. Während ich der Wahl eines sortierbaren Formats zustimme, wenn es überhaupt eine Zeichenfolge sein muss , hat ein Unix-Zeitstempel (den der Artikel nicht einmal anerkennt) alle genannten Vorteile und mehr. Bis zur Präsentation gibt es nicht einmal die Themen Zeitzonen und Sommerzeit (und politische Entscheidungen).
Kaay
18

RFC6690 - CoRE-Link-Format (Constrained RESTful Environments) Gibt jedoch nicht explizit an, welches Datumsformat in Abschnitt 2 angegeben werden soll. Das Link-Format verweist auf RFC 3986. Dies impliziert, dass die Empfehlung für den Datumstyp in RFC 3986 verwendet werden sollte.

Grundsätzlich ist RFC 3339 Datum und Uhrzeit im Internet das zu betrachtende Dokument, das lautet:

Datums- und Zeitformat zur Verwendung in Internetprotokollen, das ein Profil der Norm ISO 8601 zur Darstellung von Datum und Uhrzeit unter Verwendung des Gregorianischen Kalenders ist.

worauf es ankommt : JJJJ-MM-TTTHH: mm: ss.ss ± hh: mm

(zB 1937-01-01T12: 00: 27.87 + 00: 20)

Ist die sicherste Wette.

Matas Vaitkevicius
quelle
12

Jedes Datum / Uhrzeit-Feld in der Eingabe / Ausgabe muss im UNIX / Epoch- Format vorliegen. Dies vermeidet die Verwirrung zwischen Entwicklern auf verschiedenen Seiten der API.

Vorteile:

  • Das Epochenformat hat keine Zeitzone.
  • Epoche hat ein einzelnes Format (Unix-Zeit ist eine einzelne vorzeichenbehaftete Zahl).
  • Die Epochenzeit wird durch die Sommerzeit nicht beeinflusst.
  • Die meisten Backend-Frameworks und alle nativen iOS / Android-APIs unterstützen die Epochenkonvertierung.
  • Der Teil der lokalen Zeitkonvertierung kann vollständig auf der Anwendungsseite durchgeführt werden. Dies hängt von der Zeitzoneneinstellung des Geräts / Browsers des Benutzers ab.

Nachteile:

  • Zusätzliche Verarbeitung für die Konvertierung in UTC zum Speichern im UTC-Format in der Datenbank.
  • Lesbarkeit der Ein- / Ausgabe.
  • Lesbarkeit von GET-URLs.

Anmerkungen:

  • Zeitzonen sind ein Problem auf Präsentationsebene! Der größte Teil Ihres Codes sollte sich nicht mit Zeitzonen oder Ortszeit befassen, sondern die Unix-Zeit vertreiben.
  • Wenn Sie eine für Menschen lesbare Zeit (z. B. Protokolle) speichern möchten, sollten Sie sie zusammen mit der Unix-Zeit und nicht anstelle der Unix-Zeit speichern.
Mithun Sreedharan
quelle
1
Konnte nicht mehr zustimmen.
Jorge.V
1
Das einzige, was ich hinzufügen möchte, ist von Anfang an zu überlegen, ob Sie Millisekunden irgendwo in Ihrem System berücksichtigen müssen. Verwenden Sie in diesem Fall die Millisekundenversion des Unix-Zeitstempels.
Jamesjansson
1

Verwenden Sie immer UTC:

Zum Beispiel habe ich eine Zeitplankomponente, die einen Parameter DATETIME akzeptiert. Wenn ich dies mit einem GET-Verb aufrufe, verwende ich das folgende Format, in dem mein eingehender Parametername ScheduleDate lautet.

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

Michael K.
quelle