Управление версиями API FedEx

В FedEx используется семантическое управление версиями API. Номера версий API имеют следующий формат: «основная.дополнительная» (например, API отправлений 1.1). Новая основная версия подразумевает изменения без обратной совместимости, а новая дополнительная версия указывает на наличие изменений с обратной совместимостью.

В FedEx используется простое управление версиями URI. Это значит, что в адресе URI указывается только основная версия. Следует иметь в виду, что номер дополнительной версии в адресе URI не указывается. Для указания на конкретные версии API в этой схеме используется маршрутизация адресов URI.

Например: /ship/v1/shipments

Основные принципы управления версиями

Мы планируем реже выпускать основные версии API FedEx. При этом поддержка основной версии прекращается через два года после выпуска новой. То есть, после выпуска основной версии N версия N-1 будет поддерживаться еще в течение двух лет с момента выпуска версии N.

Например: в 2020 году выпущена основная версия 1.0. Если в 2021 году будет выпущена версия 2.0, поддержка версии 1.0 будет прекращена в 2023 году.

Дополнительные версии будут содержать новые функции и обновления.

Например: после основной версии 1.0, будут выпускаться дополнительные версии 1.1, 1.2 и т. д. для внедрения новых функций и обновлений.

В любой момент времени все конечные точки определенного API будут относиться к одной и той же основной версии. Последняя версия документации будет доступна только на портале FedEx Developer Portal. При этом краткое описание каждого API будет содержать журнал изменений с подробными сведениями об изменениях в основной и дополнительных версиях.

В каких случаях происходит выпуск основных версий API?

Мы стремимся свести к минимуму количество основных версий API. Однако бывают случаи, когда выпуск новой основной версии просто необходим. Ниже приведены основные причины необходимости выпуска новой основной версии.

• При удалении существующего цифрового значения, а также изменении формата или значения в запросе или отклике
  

  Пример. В версии N удалено перечисляемое значение “GEOGRAPHIC_COORDINATES” для элемента locationSearchCriterion; синтаксис даты ГГ-ММ-ДД заменен на ДД-ММ-ГГГГ; в отклике тип местоположения FEDEX_ONSITE заменен на ONSITE

• При удалении существующего элемента из запроса или отклика
  

  Пример. В версии N из запроса удален (или переименован) элемент pickupType

• При удалении существующего метода
  

  Пример. В версии N больше не поддерживается метод создания и отмены тегов FedEx Express.

• При переводе существующего элемента запроса из разряда необязательных или условных в обязательные
  

  Пример. В версии N номер бронирования стал обязательным элементом для отправлений FedEx Express® Freight.

• При изменениях в структуре API
  

  Пример. Изменена структура запроса и отклика.

• При внесении изменений в коды и сообщения об ошибках
  

  Пример. Код ошибки INCORRECT.WEIGHT заменен на WEIGHT.LIMIT.EXCEEDED.

В каких случаях происходит выпуск дополнительных версий API?

• При добавлении нового цифрового значения
  

  Пример. В версии N для услуги serviceType добавлен новый вариант транспортировки.

• При добавлении нового элемента
  

  Пример. Добавлен новый необязательный элемент с номером телефона брокера для международных отправлений.

• При добавлении нового метода
  

  Пример. В версии N добавлен метод изменения международных коммерческих документов после загрузки в систему.

• При переводе существующего элемента из категории обязательных в необязательные
  

  Пример. Идентификатор документа Document ID переведен в разряд необязательных элементов, поскольку система FedEx теперь может получать идентификатор документации из данных о пользователе.