Версионирование API на FastAPI и Django: как обновлять сервис и не ломать клиентов

Веб-фронтенд вы деплоите одновременно с бэкендом. С мобильными приложениями так не получится: после публикации в App Store и Google Play старые сборки живут в кармане у пользователей годами. По нашему опыту, спустя полгода после релиза до 15–25% аудитории всё ещё сидит на версиях, которые вышли до последних трёх обновлений.

Интеграции ещё менее предсказуемы. Партнёр написал клиент под ваш API два года назад, разработчик ушёл, документацию никто не открывал. Любое изменение для такого клиента — потенциальный простой.

Что именно считается breaking change:

• удаление или переименование поля в ответе;
• изменение типа данных (например, id из числа в строку);
• добавление обязательного поля в запрос;
• изменение семантики статус-кодов или формата ошибок;
• ужесточение валидации, из-за которой раньше корректные запросы возвращают 422.

Безопасными обычно считаются добавление необязательных полей и новых эндпоинтов. Но и тут есть нюанс: строгие клиенты с генерируемыми моделями (например, на Kotlin с FAIL_ON_UNKNOWN_PROPERTIES) могут упасть даже от нового поля.

Цена ошибки измеряется не только часами простоя. Это отзывы в сторах, штрафы по SLA, срочные хотфиксы и потерянное доверие партнёров. Версионирование превращает такие инциденты в плановую работу. Если вы проектируете контракт с нуля, начните с проектирования API: правильные ресурсы и форматы ответов сокращают число будущих версий вдвое.

Существует три основных подхода, и у каждого свои компромиссы. Выбор зависит от типа клиентов, инфраструктуры и зрелости команды.

1. Версия в URL (/api/v1/users). Самый популярный вариант. Он очевиден, легко кэшируется, удобно маршрутизируется на уровне nginx или API-шлюза и видна в логах. Минус: формально версия относится к ресурсу, а не к его представлению, и это нарушает пуристский REST. На практике большинству команд это не мешает.

2. Версия в заголовке (Accept: application/vnd.myapp.v2+json или X-API-Version: 2). Чистый URL и гибкость согласования контента. Но такие запросы сложнее отлаживать в браузере и через curl, а кэши должны учитывать Vary. Для публичных API это увеличивает порог входа.

3. Параметр запроса (/users?version=2). Просто в реализации и легко тестировать. Однако параметр часто теряется при проксировании, засоряет ключи кэша, а клиенты забывают его передавать и получают версию по умолчанию.

Как выбирать? Порядок рассуждений обычно такой:

1. Если API публичный или с мобильными клиентами — берите URL-версионирование.
2. Если у вас строгий hypermedia-подход и контролируемые клиенты — рассмотрите заголовки.
3. Параметр запроса оставьте для внутренних экспериментов.
4. Версионируйте только мажорные изменения: v1, v2, без v1.3.7 в адресе.

Минорные изменения вносите в рамках текущей версии с сохранением совместимости. Для сложных систем с десятками сервисов стратегию версий стоит согласовать заранее, это частая тема на консультациях по микросервисной архитектуре.

FastAPI не навязывает схему версий, зато даёт отличный инструмент: APIRouter. Каждая версия — отдельный роутер со своими схемами Pydantic и обработчиками. Общую бизнес-логику выносим в сервисный слой, чтобы не дублировать код.

Базовая структура проекта выглядит так: app/api/v1/users.py, app/api/v2/users.py, app/services/users.py. Подключение:

from fastapi import FastAPI, APIRouter
from app.api.v1 import users as users_v1
from app.api.v2 import users as users_v2

app = FastAPI(title="Shop API")

v1 = APIRouter(prefix="/api/v1")
v1.include_router(users_v1.router, tags=["users"])

v2 = APIRouter(prefix="/api/v2")
v2.include_router(users_v2.router, tags=["users"])

app.include_router(v1)
app.include_router(v2)

Чтобы у каждой версии была собственная документация, используйте подприложения через app.mount. Создайте api_v1 = FastAPI(title="Shop API v1"), подключите роутеры и смонтируйте: app.mount("/api/v1", api_v1). Тогда /api/v1/docs и /api/v1/openapi.json описывают только первую версию, а /api/v2/docs — вторую.

Схемы между версиями наследуйте осторожно. Если UserV2 наследует UserV1, изменение базовой модели незаметно затронет старый контракт. Надёжнее держать модели независимыми и покрывать контракт снапшот-тестами: сохраняйте openapi.json каждой версии и сравнивайте в CI, например через oasdiff. Падение сборки при изменении v1 — лучшая защита от случайных поломок. Подробнее о построении таких сервисов — на странице разработки на FastAPI.

DRF содержит встроенную подсистему версионирования. Классы лежат в rest_framework.versioning: URLPathVersioning, NamespaceVersioning, AcceptHeaderVersioning, QueryParameterVersioning. Для публичных API чаще всего выбирают NamespaceVersioning: версия определяется пространством имён URL.

Настройки в settings.py:

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

Маршруты в корневом urls.py:

urlpatterns = [
    path("api/v1/", include(("users.urls_v1", "v1"), namespace="v1")),
    path("api/v2/", include(("users.urls_v2", "v2"), namespace="v2")),
]

Внутри представления доступен request.version. Самый простой путь — выбирать сериализатор по версии:

class UserViewSet(ModelViewSet):
    def get_serializer_class(self):
        if self.request.version == "v2":
            return UserSerializerV2
        return UserSerializerV1

Если различий много, лучше развести представления по отдельным модулям, чем превращать код в лес условий. Для особых случаев напишите собственный класс, унаследовав BaseVersioning и переопределив determine_version, например чтобы брать версию из кастомного заголовка.

Не забывайте про документацию: drf-spectacular умеет генерировать схему под конкретную версию через параметр SPECTACULAR_SETTINGS и фильтрацию по namespace. Реализация таких решений на реальных проектах — часть нашей работы по разработке Django-приложений.

Версий не должно быть бесконечно много: каждая стоит денег на поддержку, тесты и безопасность. Поэтому нужна публичная политика. Разумный стандарт для B2B и мобильных клиентов: поддерживать минимум две мажорные версии одновременно и давать 6–12 месяцев между объявлением об устаревании и отключением. Для внутренних сервисов хватит 1–3 месяцев.

Для машиночитаемых уведомлений есть два заголовка. Deprecation (RFC 9745) сообщает, что ресурс устарел, а Sunset (RFC 8594) — когда он будет отключён. Дополнительно используйте Link с rel="sunset" или rel="deprecation" на страницу миграции.

Пример для deprecation API в Django REST Framework — миксин:

class DeprecatedMixin:
    sunset = "Sat, 31 Oct 2026 23:59:59 GMT"

    def finalize_response(self, request, response, *args, **kwargs):
        response = super().finalize_response(request, response, *args, **kwargs)
        response["Deprecation"] = "true"
        response["Sunset"] = self.sunset
        response["Link"] = '<https://example.com/docs/migrate-v2>; rel="deprecation"'
        return response

В FastAPI аналогичный эффект даёт middleware, которое добавляет заголовки к ответам с префиксом /api/v1.

План миграции клиентов можно оформить так:

1. Опубликуйте changelog и руководство по переходу с примерами запросов.
2. Включите заголовки Deprecation и Sunset в ответы старой версии.
3. Логируйте использование по API-ключам и User-Agent, чтобы знать, кто ещё сидит на v1.
4. Напишите активным клиентам лично за 90, 30 и 7 дней до отключения.
5. Перед удалением на сутки включите «brownout»: кратковременные 410 Gone, чтобы разбудить забытые интеграции.

Метрики помогают принять решение. Если на v1 осталось менее 2% трафика и эти клиенты предупреждены, отключение безопасно. Настроить такие дашборды и алерты помогут специалисты по DevOps.