**Language / Язык:** [English](../api-versions.md) | [Русский](api-versions.md)

# Версии API (PVE 6–9)

Симулятор поставляет авторитетные импортированные контракты для четырёх мажорных
версий Proxmox VE. Покрытие реестра обработчиков **100% проверено** для каждой:

| Мажор | Исходная версия | Объявленных методов | Покрытие обработчиками |
|---|---|---:|---:|
| 6 | 6.4-15 | 504 | 100% |
| 7 | 7.4-16 | 540 | 100% |
| 8 | 8.4.5 | 605 | 100% |
| 9 | 9.2.3 | 675 | 100% |

Более старые мажорные версии переиспользуют текущие семантические обработчики плюс
синонимы путей, зарегистрированные в `app/handlers/legacy_aliases.py` (например,
исторические написания путей Ceph и backup).

## Холодный старт

Задайте `CONTRACT_SNAPSHOT` путь к нормализованному снимку. Docker Compose по
умолчанию закрепляет встроенную ревизию PVE **9.2.3**.

`GET /api2/json/version` возвращает поля, производные от `source_version` **активного**
снимка.

## Горячая замена (runtime)

Просмотрите любой мажор в каталоге Web UI, затем **Apply as runtime**, или вызовите:

```http
POST /ui/api/contract/apply?major=7
```

Эффекты:

- Маршруты `/api2/json` и `/api2/extjs` в памяти заменяются под блокировкой
  приложения.
- `/version`, OpenAPI, метаданные реализации и состояние совместимости обновляются
  для нового мажора.
- Изменение **локально для процесса** и **не сохраняется**.
- Перезапуск восстанавливает `CONTRACT_SNAPSHOT`.

Просмотр каталога (`GET /ui/api/catalog?major=N`) **сам по себе** не меняет
runtime; меняет только apply.

### Рекомендации для клиентов

- Явно закрепляйте мажор в CI (env холодного старта **или** apply + проверка
  `/version` перед набором тестов).
- Горячая замена на лету может инвалидировать предположения клиента о схемах и
  путях — избегайте во время длинных прогонов Terraform/Ansible, если прогон не
  владеет переключением.
- После apply перепроверьте `/admin/compatibility` для активного runtime.

## Режимы fallback

`CONTRACT_FALLBACK` управляет поведением для необъявленных обработчиков:

| Значение | Поведение |
|---|---|
| `error` (по умолчанию) | HTTP 501 с явным сообщением в стиле pending-handler |
| `schema-default` | Синтез возвращаемого значения из схемы контракта |
| `fixture` | Только fixture-данные, встроенные в контракт метода |

При полном покрытии обработчиков активного контракта объявленные методы не должны
попадать в fallback. Оставляйте `error`, чтобы регрессии оставались видимыми.

## Evidence vs реестр

**Покрытие реестра** означает, что у каждого объявленного метода зарегистрирован
семантический обработчик (нет систематического 501 для этого контракта).

**Verified** в смысле этого проекта — мажорные версии прогоняются через наборы
совместимости и автоматизацию на наличие обработчиков для 6–9. Многомерный evidence
JSON может со временем расширяться для более глубоких edge-case заявлений;
предпочитайте живой `/admin/compatibility`, когда процесс запущен.

См. [Совместимость](compatibility.md).