Рекомендуемый формат даты для REST GET API

105

Какой рекомендуемый формат метки времени для API REST GET, например:

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

Я думаю, что фактический формат даты должен быть форматом ISO 8601, например, YYYY-MM-DDThh:mm:ssZдля времени UTC.

Следует ли использовать версию ISO 8601 без дефисов и двоеточий, например:

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

или мы должны кодировать формат ISO 8601, используя, например, кодировку base64?

Лоренцо Полидори
источник
Почему формат ISO 8601 не подходит для вас?
Johannes
@Johannes, формат ISO 8601 (в версии без дефисов и двоеточий) будет в порядке, мне просто интересно, есть ли какой-то рекомендуемый подход для представления дат в URL-адресах
Лоренцо Полидори

Ответы:

77

REST не имеет рекомендованного формата даты. На самом деле все сводится к тому, что лучше всего подходит для вашего конечного пользователя и вашей системы. Лично я хотел бы придерживаться стандарта, такого как у вас для ISO 8601 (закодированный URL).

Если не имеющие уродливые URI является проблемой (например , не включая URL - адрес закодированной версии :, -, в вас URI) и адресация (человек) не так важно, вы могли бы также рассмотреть вопрос о времени эпохи (например http://example.com/start/1331162374). URL выглядит немного чище, но вы определенно теряете удобочитаемость.

Это /2012/03/07еще один формат, который вы часто видите. Я полагаю, вы могли бы расширить это. Если вы пойдете по этому пути, просто убедитесь, что вы всегда находитесь в режиме GMT ​​(и четко укажите это в документации), или вы также можете включить какой-то индикатор часового пояса.

В конечном итоге все сводится к тому, что работает для вашего API и вашего конечного пользователя. Ваш API должен работать на вас, а не на вас ;-).

лапша
источник
12
Спасибо, очень полезный ответ. Я думаю, что выберу сжатую версию ISO 8601 (т.е. http://api.example.com/start_date/YYYYMMDDThhmmssZ), которая удобна для чтения и чистых URL-адресов.
Лоренцо Полидори
7
Но JSON действительно имеет рекомендованную формат даты и это ISO 8601 :)
Radu Potop
5
@RaduPotop Да, но мы говорим о стандартах HTTP и URI. Я не уверен, при чем здесь JSON.
nategood 05
3
Я просто хочу отметить, что дефисы не нужно кодировать URL-адресом.
user128216 05
1
Эта ссылка - agiletribe.wordpress.com/2015/06/10/jsonrest-api-handling-dates рекомендует целочисленную эпоху, чтобы избежать проблем с удобочитаемостью, которые могут возникнуть при использовании формата iso-8601. Дайте мне знать, если у вас другие взгляды
Энди Дюфрен
97

Ознакомьтесь с этой статьей, чтобы узнать о 5 законах даты и времени API ЗДЕСЬ :

  • Закон №1: Используйте ISO-8601 для своих свиданий
  • Закон №2: принимайте любой часовой пояс
  • Закон № 3: Храните его в UTC
  • Закон №4: вернуть его в UTC
  • Закон # 5: не тратьте время, если оно вам не нужно

Больше информации в документации.

Мохамед-Ибрахим
источник
2
-1, так как 2017-11-20T11%3A00%3A00Zпросто не очень читается. Кроме того (специфично для IIS) кажется очень параноидальным в отношении двоеточий в URL-адресах, даже если они закодированы.
Iain
3
Эта ссылка - agiletribe.wordpress.com/2015/06/10/jsonrest-api-handling-dates рекомендует целочисленную эпоху, чтобы избежать проблем с удобочитаемостью, которые могут возникнуть при использовании формата iso-8601. Дайте мне знать, если у вас разные взгляды.
Энди Дюфрен
5
Обратите внимание, что дефисы и точки не являются зарезервированными символами в URL-адресах. Только двоеточия требуют кодировки URL ( en.wikipedia.org/wiki/Percent-encoding ). В ISO-8601 ( en.wikipedia.org/wiki/ISO_8601 ) дефисы обязательны, но двоеточия необязательны. Поэтому правильные варианты ISO-8601 для использования в URL-адресах: YYYY-MM-DDThhmmssZ и YYYY-MM-DDThhmmss.mmmZ, если вам нужна более высокая точность.
Брюс Адамс
Статья, на которую часто ссылаются и которая активно обсуждается. Хотя я согласен с выбором сортируемого формата, если он вообще должен быть строкой , временная метка unix (которая даже не упоминается в статье) имеет все указанные преимущества и многое другое. До презентации вопросов о часовых поясах и переходе на летнее время (и политических решениях) даже не существует.
каай
18

RFC6690 - Формат ссылок в ограниченных средах RESTful (CoRE) В разделе 2 явно не указывается, какой формат даты должен быть. Формат ссылки указывает на RFC 3986. Это означает, что следует использовать рекомендации для типа даты в RFC 3986 .

По сути, RFC 3339 Date and Time в Интернете - это документ, на который нужно смотреть, в котором говорится:

формат даты и времени для использования в Интернет-протоколах, который является профилем стандарта ISO 8601 для представления даты и времени с использованием григорианского календаря.

к чему это сводится: ГГГГ-ММ-ддТЧЧ: мм: сс.сс ± чч: мм

(например, 1937-01-01T12: 00: 27.87 + 00: 20)

Самая безопасная ставка.

Матас Вайткявичюс
источник
13

Каждое поле datetime во вводе / выводе должно быть в UNIX / эпохе. формате . Это позволяет избежать путаницы между разработчиками с разных сторон API.

Плюсы:

  • Формат Epoch не имеет часового пояса.
  • Epoch имеет единый формат (время Unix - это однозначное число).
  • Переход на летнее время не влияет на время эпохи.
  • Большинство серверных фреймворков и все собственные API для iOS / Android поддерживают преобразование эпох.
  • Часть преобразования местного времени может быть выполнена полностью на стороне приложения, в зависимости от настройки часового пояса устройства / браузера пользователя.

Минусы:

  • Дополнительная обработка для преобразования в UTC для хранения в базе данных в формате UTC.
  • Читаемость ввода / вывода.
  • Читаемость GET URL.

Ноты:

  • Часовые пояса - это проблема уровня представления! Большая часть вашего кода не должна иметь дело с часовыми поясами или местным временем, он должен передавать время Unix.
  • Если вы хотите сохранить время, удобное для чтения (например, журналы), рассмотрите возможность сохранения его вместе со временем Unix, а не вместо времени Unix.
Митхун Сридхаран
источник
1
Не могу с этим согласиться.
Хорхе
1
Единственное, что я хотел бы добавить к этому, - это с самого начала подумать, нужно ли вам учитывать миллисекунды в любом месте вашей системы. Если да, используйте миллисекундную версию отметки времени Unix.
jamesjansson
1

Всегда используйте UTC:

Например, у меня есть компонент расписания, который принимает один параметр DATETIME. Когда я вызываю это с помощью команды GET, я использую следующий формат, в котором имя моего входящего параметра - scheduleDate.

Пример:
https: // localhost / api / getScheduleForDate? ScheduleDate = 2003-11-21T01: 11: 11Z

Майкл К
источник