Версионирование
Last updated
Was this helpful?
Last updated
Was this helpful?
Версионирование интерфейса - это просто "вежливый" способ убить развернутых клиентов.
.
Версионность API позволяет изменять поведение различных клиентов. DRF предусматривает несколько различных схем версионирования.
Версионность определяется входящим запросом клиента и может быть основана либо на URL запроса, либо на заголовках запроса.
Существует несколько правильных подходов к определению версий. , особенно если вы разрабатываете очень долгосрочные системы с множеством клиентов вне вашего контроля.
Если версионность API включена, атрибут request.version
будет содержать строку, соответствующую версии, запрошенной во входящем клиентском запросе.
По умолчанию версионность не включена, и request.version
всегда будет возвращать None
.
Различное поведение в зависимости от версии
Как вы будете изменять поведение API, зависит от вас, но один из примеров, который обычно может понадобиться, - это переход на другой стиль сериализации в новой версии. Например:
Обратные URL для версионных API
Функция reverse
, включенная в DRF, связана со схемой версионирования. Вам нужно убедиться, что вы включили текущий request
в качестве именованного аргумента, как, например.
Приведенная выше функция будет применять любые преобразования URL, соответствующие версии запроса. Например:
Если используется NamespaceVersioning
, и версия API равна 'v1', то для поиска URL используется 'v1:bookings-list'
, что может привести к URL типа http://example.org/v1/bookings/
.
Если используется QueryParameterVersioning
, и версия API была '1.0', то возвращаемый URL может быть чем-то вроде http://example.org/bookings/?version=1.0
.
Версифицированные API и сериализаторы с гиперссылками
При использовании стилей сериализации с гиперссылками вместе со схемой версионирования на основе URL обязательно включайте запрос в качестве контекста для сериализатора.
Это позволит всем возвращаемым URL-адресам включать соответствующие версии.
Схема версионирования определяется ключом настройки DEFAULT_VERSIONING_CLASS
.
Если оно не задано явно, значение для DEFAULT_VERSIONING_CLASS
будет равно None
. В этом случае атрибут request.version
всегда будет возвращать None
.
Вы также можете установить схему версионирования для отдельного представления. Обычно вам не нужно этого делать, поскольку логичнее иметь единую схему версионирования, используемую глобально. Если это необходимо, используйте атрибут versioning_class
.
Другие параметры версионирования
Следующие ключи настроек также используются для управления версионированием:
DEFAULT_VERSION
. Значение, которое должно использоваться для request.version
, когда информация о версиях отсутствует. По умолчанию None
.
ALLOWED_VERSIONS
. Если задано, это значение ограничивает набор версий, которые могут быть возвращены схемой версионирования, и выдает ошибку, если предоставленная версия не входит в этот набор. Обратите внимание, что значение, используемое для параметра DEFAULT_VERSION
, всегда считается частью набора ALLOWED_VERSIONS
(если оно не равно None
). По умолчанию None
.
VERSION_PARAM
. Строка, которая должна использоваться для любых параметров версионирования, например, в типе медиа или параметрах запроса URL. По умолчанию имеет значение 'version'
.
Вы также можете установить свой класс версионности плюс эти три значения на основе каждого представления или каждого набора представлений, определив свою собственную схему версионности и используя переменные класса default_version
, allowed_versions
и version_param
. Например, если вы хотите использовать URLPathVersioning
:
Эта схема требует от клиента указать версию как часть типа медиа в заголовке Accept
. Версия включается в качестве параметра медиатипа, дополняющего основной медиатип.
Вот пример HTTP-запроса с использованием стиля версионирования заголовка accept.
В приведенном выше примере запроса атрибут request.version
вернет строку '1.0'
.
Использование заголовков accept с медиатипами поставщиков
Теперь ваши клиентские запросы будут выглядеть следующим образом:
Эта схема требует, чтобы клиент указывал версию как часть пути URL.
Ваш URL conf должен включать шаблон, соответствующий версии, с именованным аргументом 'version'
, чтобы эта информация была доступна схеме версионирования.
Для клиента эта схема аналогична URLPathVersioning
. Единственное различие заключается в том, как она настраивается в вашем приложении Django, поскольку она использует интервалы между именами URL, вместо именованных аргументов URL.
При такой схеме атрибут request.version
определяется на основе namespace
, соответствующего пути входящего запроса.
В следующем примере мы даем набору представлений два различных возможных префикса URL, каждый из которых относится к разным пространствам имен:
И URLPathVersioning
, и NamespaceVersioning
разумны, если вам нужна простая схема версионирования. Подход URLPathVersioning
может лучше подойти для небольших специальных проектов, а NamespaceVersioning
, вероятно, проще в управлении для больших проектов.
Схема версионности имени хоста требует от клиента указать запрашиваемую версию как часть имени хоста в URL.
Например, ниже приведен HTTP-запрос к URL http://v1.example.com/bookings/
:
По умолчанию эта реализация ожидает, что имя хоста будет соответствовать этому простому регулярному выражению:
Обратите внимание, что первая группа заключена в скобки, что указывает на то, что это совпадающая часть имени хоста.
Версионность на основе имени хоста может быть особенно полезна, если у вас есть требования направлять входящие запросы на разные серверы в зависимости от версии, поскольку вы можете настроить разные записи DNS для разных версий API.
Эта схема представляет собой простой стиль, который включает версию в качестве параметра запроса в URL. Например:
Для реализации пользовательской схемы версионирования, подкласс BaseVersioning
и переопределите метод .determine_version
.
В следующем примере используется пользовательский заголовок X-API-Version
для определения запрашиваемой версии.
Если ваша схема версионирования основана на URL запроса, вы также захотите изменить способ определения версионированных URL. Для этого вам следует переопределить метод .reverse()
в классе. Примеры см. в исходном коде.
Версионирование на основе принимаемых заголовков как , хотя в зависимости от требований клиента могут подойти и другие стили.
Строго говоря, медиатип json
не указан как . Если вы создаете хорошо специфицированный публичный API, вы можете рассмотреть возможность использования . Для этого настройте свои рендереры на использование рендерера на основе JSON с пользовательским медиатипом:
Схема HostNameVersioning
может быть неудобна для использования в режиме отладки, так как обычно вы обращаетесь к необработанному IP-адресу, например, 127.0.0.1
. Существуют различные онлайн-уроки о том, как , которые могут оказаться полезными в этом случае.