Сообщить об ошибкеКороткий ответ
Версия в URL позволяет вносить несовместимые изменения в API, продолжая обслуживать старых клиентов на прежней версии, пока они не перейдут на новую — это один из простых способов версионирования контракта.
Как это работает подробнее
при изменении формата ответа, удалении поля или смене поведения эндпоинта несовместимым образом создаётся новая версия (/v2/...), а старая версия продолжает работать без изменений для существующих интеграций.
Пример кода
example.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/v1/users/{user_id}")
def get_user_v1(user_id: int):
return {"id": user_id, "full_name": "Иван Иванов"} # одно строковое поле
@app.get("/v2/users/{user_id}")
def get_user_v2(user_id: int):
return {"id": user_id, "first_name": "Иван", "last_name": "Иванов"} # разбито на два поля — несовместимое изменениеЧто использовать на практике
- Рекомендация. версионирование в URL — не единственный способ (есть версия через заголовок или content negotiation), но он самый явный и простой для отладки (видно прямо в адресе, легко тестировать curl'ом). Важно заранее договориться о политике поддержки старых версий (сколько версий поддерживается одновременно, срок депрекации).
Подводные камни
- Риски. менять поведение существующего эндпоинта без увеличения версии, молча ломая всех текущих клиентов; увеличивать версию при любом, даже совместимом изменении (например, добавлении нового опционального поля), что создаёт ненужную фрагментацию и нагрузку на поддержку нескольких версий.