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

# vSphere API coverage matrix

Auto-oriented registry: [`app/vsphere/rest/coverage.py`](../app/vsphere/rest/coverage.py).  
Broadcom universe stubs: [`app/vsphere/rest/universe.json`](../app/vsphere/rest/universe.json) (from the public operations index).  
Per-major floors + stub OpenAPI bundles: [`app/vsphere/contracts/matrix.py`](../app/vsphere/contracts/matrix.py) → `contracts/vsphere/<version>/manifest.json`.

## Broadcom vs this simulator

Public source (scraped): [vSphere Automation API Operations Index (9.1 Latest)](https://developer.broadcom.com/xapis/vsphere-automation-api/latest/operation-index/)

| Surface | Count | Notes |
|---|---:|---|
| Broadcom Operations Index | **1348** | GET 628 / POST 422 / DELETE 114 / PUT 93 / PATCH 91 |
| Generated unique `verb + path` routes | **~1037** | Same HTTP path can back several named ops (`?action=…`, `$Task`) |
| Simulator registry (core + stubs + `/rest`) | **1077** | Core deep handlers overwrite stub entries on the same path |
| Core deep handlers | **104** | Seeded inventory / lifecycle / authz behaviour |
| DB-backed surface rows (`vsphere_api_state`) | **~540+** | Seeded for every GET `/api` route + lab extras |

Regenerate universe after refreshing the index dump:

```bash
python scripts/generate_vsphere_universe.py
make vsphere-bundles
```

Refresh live stats / regenerate artifacts:

```bash
curl -sk https://localhost/ui/api/compatibility?major=9
make vsphere-surface
python scripts/write_vsphere_bundles.py
python scripts/write_vsphere_evidence.py
```

| Major | Label | Implemented / universe | Coverage | Notes |
|---|---|---:|---:|---|
| 6 | vSphere 7.0 | 31 / 1077 | 2.9% | Catalog/evidence floor only |
| 7 | vSphere 7.0 U3 | 77 / 1077 | 7.2% | Catalog/evidence floor only |
| 8 | vSphere 8.0 | 103 / 1077 | 9.6% | Catalog/evidence floor only |
| 9 | vSphere 8.0 U2 / Automation 9.1 surface | **1077 / 1077** | **100%** | Deep handlers + DB-backed Broadcom surface |

Numbers come from `GET /ui/api/compatibility?major=N` and `evidence/vsphere-*.json` (`make vsphere-bundles`).

Hot-swap (`POST /ui/api/contract/apply?major=N`) changes the **catalog** major used by the Web UI / evidence reports. **Runtime always serves the full registered surface** — known paths are never HTTP 501’d by version floor.

## Planes

| Plane | Default | Notes |
|---|---|---|
| Native REST `/api`, `/rest` | on | Primary lab surface |
| Native SOAP `/sdk` | on | PropertyCollector subset + VM tasks |
| Proxmox `/api2/*` stub | **off** (`ENABLE_PVE_STUB=false`) | Optional legacy |

## Auth & synthetic data

| Item | Detail |
|---|---|
| Users | `administrator`, `readonly`, `operator`, `vmadmin` `@vsphere.local` / `VMware1!` |
| AuthZ | Role → privilege gate on mutate endpoints (403 `unauthorized`) |
| Seed `large` | 10 hosts, **1000 VMs**, 4 datastores, DVS, folders, permissions |
| Seed `demo-cluster` | 20 hosts, 1000 VMs (UI demo load) |
| Seed `small` | 3 hosts, 5 named VMs (tests) |

## REST domains

### Deep (core) at major 9

- Session / CIS tasks / AuthZ roles+permissions / identity providers / TLS cert stub
- VM list/get/create/delete/power, hardware, snapshots, clone, relocate, tools, guest identity/networking/power/customization, console tickets, template/unregister
- Host list/get + maintenance + storage-device + networking
- Datastore list/get + file metadata
- Network list + DVS/DVPG create
- Datacenter / cluster / folder (+children) / resource-pool CRUD
- Tagging, content library + OVF, storage policies (+ VM associations), privileges
- Appliance version/health/networking/timesync
- `vapi` metamodel service list stub

### DB-backed Automation surface (Broadcom universe catch-all)

Remaining Automation API routes from the 9.1 operations index are registered and answered by [`app/vsphere/rest/stub_surface.py`](../app/vsphere/rest/stub_surface.py) against PostgreSQL:

- table `vsphere_api_state` (migration `011_vsphere_api_state.sql`)
- seeded by `seed_api_surface()` on every profile including **`demo-cluster`** / UI `POST /ui/api/demo/load`
- inventory overlay for VM hardware (cdrom/scsi/boot/…), host networking/storage, tagging, content libraries
- PUT/PATCH persist into `vsphere_api_state`; POST appends collection rows; DELETE removes them

No `"stub": true` markers — probes require real seeded payloads on major 9.

## SOAP domains (govmomi / Terraform / Pulumi / pyvmomi)

- RetrieveServiceContent (+ TaskManager / SearchIndex / GuestOperationsManager / FileManager / OvfManager)
- RetrieveProperties / RetrievePropertiesEx / **ContinueRetrievePropertiesEx** (pagination tokens; `<objects>` plural)
- PropertyCollector: parent-chain Ancestors, one-hop `childEntity` ListFolder, ContainerView `view` traversal
- Folder.childType as `ArrayOfString`; string props carry `xsi:type="xsd:string"` (govmomi decode)
- Datastore.host as `ArrayOfDatastoreHostMount`; Cluster/Host **environmentBrowser**
- **QueryConfigOption** / QueryConfigOptionEx / QueryConfigOptionDescriptor / QueryConfigTarget
- CreateFilter / WaitForUpdatesEx (version tokens; empty polls)
- FindByInventoryPath (govmomi paths omit root `Datacenters`), FindByUuid/Dns/Ip, FindChild
- **CreateVM_Task** / CreateChildVM_Task, CreateFolder, Power/Clone/Snapshot/Rename/Reconfig/Relocate/Destroy/Unregister/MarkAsTemplate/CustomizeVM_Task + CancelTask
- Guest file ops: ListFilesInGuest, InitiateFileTransferTo/FromGuest, DeleteFileInGuest, MakeDirectoryInGuest
- Real task IDs from `vsphere_tasks` (including `info.result` MoRef on create/clone)
- `/sdk/vimService.wsdl`, `/sdk/about.do`, `/pbm` stub
- Type-strict MOR lookup: `VirtualApp:resgroup-*` does not resolve a plain ResourcePool (Terraform CreateVM path)

## REST extras for Ansible / Python apps

- VM power returns `{ "task": "task-…" }` for CIS task polling
- Guest virtual filesystem: `/api/vcenter/vm/{vm}/guest/filesystem` (+ local-filesystem listing)
- Content library update/download sessions for OVF push/pull lab flows

## Legacy `/rest`

`{ "value": … }` wrappers for vm/host/datastore/network/datacenter/cluster/power/appliance.

## Contract majors (browse vs runtime)

Hot-swap (`POST /ui/api/contract/apply?major=N`) still switches the **catalog** major for UI browse/evidence. **Runtime always serves the full registered surface** with deep handlers or DB-backed stubs — known paths are never HTTP 501’d by version floor. Catalog floors remain historical for documentation only.

## Platform surfaces (lab-available)

These were historically “deferred”; they now return **non-empty seeded lab data** and accept basic mutate:

| Area | REST | SOAP |
|---|---|---|
| NSX (tier0 / projects / edges / VPC / subnets) | Seeded Automation paths under `namespace-management` / `namespaces` | — |
| Supervisor / WCP | namespaces, VM classes, supervisor summary/identity, infra policies | — |
| vSAN | Storage policies with `policy_type: VSAN` (+ RAID1 lab policy) | — |
| SAML / OIDC | `GET/POST/PATCH/DELETE /api/vcenter/identity/providers` (LocalOS + OIDC + SAML) | — |
| VECS / certs | TLS, TLS CSR, trusted-root-chains, supervisor certs/signing-requests | — |
| HttpNfcLease | `PUT/GET /nfc/{lease}/files/...` | `ImportVApp_Task`, `CreateImportSpec`, lease progress/complete |
| Guest customization | GET+POST `/api/vcenter/vm/{vm}/guest/customization` | `CustomizeVM_Task` |

This is still a **lab-grade** stand-in (not a binary-compatible NSX Manager / real VECS store / full Broadcom device XML matrix). Perf/Event/Alarm remain answered but not deeply simulated.