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

# Версии API (vSphere catalog majors 6–9)

Web UI и evidence/compatibility отчёты просматривают четыре целочисленных **catalog
majors**, которые сопоставляются с label floors vSphere Automation API:

| Major | Метка vSphere | Строка версии contract |
|---|---|---|
| 6 | 7.0 | `7.0.0` |
| 7 | 7.0 U3 | `7.0.3` |
| 8 | 8.0 | `8.0.0` |
| 9 | 8.0 U2 (Automation 9.1 surface) | `8.0.2` |

Определения находятся в [`app/vsphere/contracts/matrix.py`](../../app/vsphere/contracts/matrix.py)
(`VERSIONS`, `PATH_FLOOR`). Каждый зарегистрированный REST path имеет **floor** —
наименьший major, при котором он появляется в catalog — из того же
модуля. Undated paths по умолчанию получают наивысший major (9), пока не catalogued.

## Runtime vs catalog

Это самое важное различие в проекте:

- **Catalog major** — управляет тем, что показывает Web UI endpoint tree, `/ui/api/catalog`,
  и compatibility/evidence отчёты для данного major.
- **Runtime surface** — симулятор всегда обслуживает **полную зарегистрированную
  route table** с deep handlers или DB-backed stubs, независимо от
  активного catalog major. Известный path никогда не возвращается как HTTP 501 из-за
  version floor.

Hot-swap catalog major — это **documentation/browse**
переключатель, а не compatibility gate для live traffic. См.
[`available_for_request()`](../../app/vsphere/contracts/matrix.py) для точной
политики.

## Cold start

`GET /api/appliance/system/version` сообщает version string текущего
выбранного runtime source (по умолчанию `8.0.2` / major 9, если процесс не
переопределяет `app.state.runtime_source_version`).

## Hot-swap (catalog browse)

Просматривайте любой major в Web UI catalog или вызывайте:

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

Эффекты:

- Web UI catalog, `/ui/api/compatibility` и evidence отчёты переключаются на
  floor major 7 и ledger (`evidence/vsphere-7.0.3.json`).
- Изменение **process-local** и **не сохраняется**; restart возвращает
  default (major 9).
- Зарегистрированные REST/SOAP routes продолжают отвечать своими реальными
  handlers независимо от применённого major.

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

- Большинству клиентов (pyvmomi, govmomi, Terraform, Pulumi, Ansible `uri`) не
  нужно pin'ить catalog major — runtime surface не меняет форму
  на его основе.
- Используйте catalog majors, когда нужно, чтобы Web UI / evidence view
  отражали более старую метку vSphere для документации или скриншотов.
- После apply перепроверьте `/ui/api/compatibility?major=N` для активного
  catalog state.

## Регенерация catalog artifacts

```bash
make vsphere-bundles     # stub OpenAPI matrices + evidence ledgers
make vsphere-universe    # regenerate universe.json from the Broadcom operations index
make evidence            # regenerate per-major verified surface evidence ledgers
```

См. [Поверхность API](api-surface.md) и [Совместимость](compatibility.md).