Как реализовать версионирование API в Django REST Framework

Как реализовать версионирование API в DRF?

Версионирование API позволяет развивать контракт без немедленного нарушения работы существующих клиентов. В DRF для этого можно использовать версии в URL, query parameter, заголовке Accept или hostname; наиболее понятный и распространённый вариант — URL вида /api/v1/....

Подробный ответ

Зачем нужно версионирование

Версия API фиксирует контракт для клиента. Если нужно несовместимо изменить поля, формат ответа или поведение endpoint, новую версию выпускают отдельно и дают клиентам время перейти на неё.

Версии в URL

Самый прозрачный вариант — включить версию в путь: /api/v1/articles/ и /api/v2/articles/. Для Django-проекта это можно организовать через отдельные URL-модули и namespace.

from django.urls import include, path

urlpatterns = [
    path('api/v1/', include('api.v1.urls')),
    path('api/v2/', include('api.v2.urls')),
]

Versioning classes DRF

DRF предоставляет классы versioning: URLPathVersioning, NamespaceVersioning, QueryParameterVersioning, AcceptHeaderVersioning и HostNameVersioning. Стратегию можно задать глобально или на уровне конкретного view.

REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
    'DEFAULT_VERSION': 'v1',
    'ALLOWED_VERSIONS': ['v1', 'v2'],
}

Как поддерживать версии

Важно не копировать весь проект при каждом релизе. Общую доменную логику и сервисы стоит переиспользовать, а различия изолировать в serializers, views, URL-слое и адаптерах контрактов. Нужны документация, срок поддержки старой версии, deprecation policy и метрики использования версий.

Когда версия не нужна

Добавление необязательного поля обычно можно сделать обратно совместимо без новой версии. Версию имеет смысл повышать при действительно breaking changes: удалении или переименовании полей, изменении типов, семантики и формата ответа.

Как ответить на собеседовании

Для публичного API я чаще выбираю версии в URL, например /api/v1/, потому что это прозрачно для клиентов. В DRF можно использовать готовые versioning classes; общую бизнес-логику оставляю общей, а изменения контракта изолирую на уровне serializers и views.