inecs
f8d3cbdd59
Add the FastAPI app, PostgreSQL migrations, Docker/Helm packaging, API contracts, docs, client examples, and the unit/integration/compatibility test suite for local client and tooling labs without a real vCenter.
78 lines
2.9 KiB
Markdown
78 lines
2.9 KiB
Markdown
**Language / Язык:** [English](api-versions.md) | [Русский](ru/api-versions.md)
|
||
|
||
# API versions (vSphere catalog majors 6–9)
|
||
|
||
The Web UI and evidence/compatibility reports browse four integer **catalog
|
||
majors** that map onto vSphere Automation API label floors:
|
||
|
||
| Major | vSphere label | Contract version string |
|
||
|---|---|---|
|
||
| 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` |
|
||
|
||
Definitions live in [`app/vsphere/contracts/matrix.py`](../app/vsphere/contracts/matrix.py)
|
||
(`VERSIONS`, `PATH_FLOOR`). Each registered REST path has a **floor** — the
|
||
lowest major at which it appears in the catalog — sourced from the same
|
||
module. Undated paths default to the highest major (9) until catalogued.
|
||
|
||
## Runtime vs catalog
|
||
|
||
This is the most important distinction in the project:
|
||
|
||
- **Catalog major** — controls what the Web UI endpoint tree, `/ui/api/catalog`,
|
||
and compatibility/evidence reports show for a given major.
|
||
- **Runtime surface** — the simulator always serves the **full registered
|
||
route table** with deep handlers or DB-backed stubs, independent of the
|
||
active catalog major. A known path is never returned as HTTP 501 because of
|
||
a version floor.
|
||
|
||
Hot-swapping the catalog major is therefore a **documentation/browse**
|
||
switch, not a compatibility gate on live traffic. See
|
||
[`available_for_request()`](../app/vsphere/contracts/matrix.py) for the exact
|
||
policy.
|
||
|
||
## Cold start
|
||
|
||
`GET /api/appliance/system/version` reports the version string of the
|
||
currently selected runtime source (defaults to `8.0.2` / major 9 unless the
|
||
process overrides `app.state.runtime_source_version`).
|
||
|
||
## Hot-swap (catalog browse)
|
||
|
||
Browse any major in the Web UI catalog, or call:
|
||
|
||
```http
|
||
POST /ui/api/contract/apply?major=7
|
||
```
|
||
|
||
Effects:
|
||
|
||
- The Web UI catalog, `/ui/api/compatibility`, and evidence reports switch to
|
||
major 7's floor and ledger (`evidence/vsphere-7.0.3.json`).
|
||
- The change is **process-local** and **not persisted**; a restart returns to
|
||
the default (major 9).
|
||
- REST/SOAP routes already registered continue to answer with their real
|
||
handlers regardless of the applied major.
|
||
|
||
### Client guidance
|
||
|
||
- Most clients (pyvmomi, govmomi, Terraform, Pulumi, Ansible `uri`) do not
|
||
need to pin a catalog major — the runtime surface does not change shape
|
||
based on it.
|
||
- Use catalog majors when you specifically want the Web UI / evidence view to
|
||
reflect an older vSphere label for documentation or screenshots.
|
||
- After apply, re-check `/ui/api/compatibility?major=N` for the active
|
||
catalog state.
|
||
|
||
## Regenerating 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
|
||
```
|
||
|
||
See [API surface](api-surface.md) and [Compatibility](compatibility.md).
|