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.
92 lines
5.6 KiB
Markdown
92 lines
5.6 KiB
Markdown
**Language / Язык:** [English](../api-surface.md) | [Русский](api-surface.md)
|
|
|
|
# Поверхность API
|
|
|
|
## Путь запроса
|
|
|
|
1. Middleware назначает или пересылает ID запроса (`REQUEST_ID_HEADER`).
|
|
2. FastAPI направляет запрос в роутер vSphere REST (`/api`, `/rest`), роутер
|
|
SOAP (`/sdk`) или (если `ENABLE_PVE_STUB=true`) в опциональный legacy-стаб.
|
|
3. `/api/session` (либо `/rest/com/vmware/cis/session`, либо SOAP `Login`)
|
|
определяет принципала и выдаёт `vmware-api-session-id`.
|
|
4. Зависимости `require_read` / `require_privilege(...)` проверяют роли
|
|
сессии перед раскрытием или мутацией ресурсов.
|
|
5. Глубокий обработчик (базовая логика инвентаря/жизненного цикла/тегов/
|
|
контента/appliance) или DB-backed поверхность стабов выполняется против
|
|
состояния, хранимого в PostgreSQL.
|
|
6. Долгие операции (power, clone, relocate, snapshot, деплой OVF) создают
|
|
долговечную CIS-задачу и возвращают `{ "task": "task-…" }`.
|
|
|
|
## Две REST-поверхности в одном реестре
|
|
|
|
- **Core (глубокие) обработчики** — ~104 комбинации verb+path в
|
|
[`app/vsphere/rest/router.py`](../../app/vsphere/rest/router.py),
|
|
`vm_ext.py`, `inventory_ext.py`, `platform_rest.py`, `tagging_rest.py`,
|
|
`content_rest.py`, `appliance_ext.py`, `nfc_rest.py`, `tasks.py`. Они
|
|
читают и мутируют напрямую seeded-таблицы инвентаря/тегов/контента/
|
|
appliance.
|
|
- **DB-backed поверхность стабов** —
|
|
[`app/vsphere/rest/stub_surface.py`](../../app/vsphere/rest/stub_surface.py)
|
|
отвечает на оставшиеся маршруты индекса операций Broadcom Automation API
|
|
(зарегистрированные из `universe.json`) против `vsphere_api_state`. GET
|
|
возвращает живые payload'ы, производные от инвентаря, когда это возможно,
|
|
иначе — seeded-строки; PUT/PATCH сохраняются в `vsphere_api_state`; POST
|
|
добавляет строки коллекции; DELETE их удаляет. Маркер `"stub": true` не
|
|
возвращается — зонды видят реальные seeded-payload'ы.
|
|
|
|
Обе поверхности используют одну таблицу маршрутов; core-обработчики имеют
|
|
приоритет над записями стабов, зарегистрированными для того же verb+path.
|
|
|
|
## Legacy `/rest`
|
|
|
|
[`app/vsphere/rest/legacy.py`](../../app/vsphere/rest/legacy.py) оборачивает
|
|
чтения vm/host/datastore/network/datacenter/cluster/power/appliance (и
|
|
power ВМ) в конверты `{ "value": … }` для более старых клиентов
|
|
`com.vmware.vcenter.*`.
|
|
|
|
## Ошибки ([`app/vsphere/errors.py`](../../app/vsphere/errors.py))
|
|
|
|
| Статус | `error_type` | Типичная причина |
|
|
|---|---|---|
|
|
| 400 | `invalid_argument` / `already_exists` | Некорректное тело, дублирующееся имя |
|
|
| 401 | `unauthenticated` | Отсутствующая/недействительная/истёкшая сессия |
|
|
| 403 | `unauthorized` | У сессии нет требуемой привилегии |
|
|
| 404 | `not_found` | Неизвестный параметр MOID/path |
|
|
| 409 | (зависит от обработчика) | Недопустимый переход состояния питания, конфликт блокировки |
|
|
| 501 | `error` | Достижимо только через fallback опционального legacy-стаба для необъявленных методов |
|
|
|
|
Все тела ошибок следуют форме vSphere Automation:
|
|
`{ "error_type": "...", "messages": [{ "default_message": "...", "id": "...", "args": [] }] }`.
|
|
|
|
## Задачи
|
|
|
|
Асинхронная работа (power, clone, snapshot, relocate, деплой OVF, guest
|
|
customize) возвращает id задачи. Опрашивайте:
|
|
|
|
```text
|
|
GET /api/cis/tasks/{task}
|
|
```
|
|
|
|
Строки задач фиксируются в `vsphere_tasks`; `progress` равен `100`, как
|
|
только `status` становится `SUCCEEDED`/`FAILED`. HTTP 200/201 на запросе
|
|
мутации означает «принято», а не «ВМ уже в конечном состоянии». См.
|
|
[Задачи](domains/tasks.md).
|
|
|
|
## Исследование
|
|
|
|
- Интерактивная документация FastAPI: `/docs`
|
|
- Инспектор методов в Web UI: `/` → каталог → метод
|
|
- Вспомогательные API UI: `/ui/api/catalog`, `/ui/api/method`,
|
|
`/ui/api/compatibility`
|
|
- Реестр покрытия: [`app/vsphere/rest/coverage.py`](../../app/vsphere/rest/coverage.py)
|
|
- Матрица уровней пути / каталога: [`app/vsphere/contracts/matrix.py`](../../app/vsphere/contracts/matrix.py)
|
|
|
|
## Эндпоинты совместимости
|
|
|
|
| Path | Формат |
|
|
|---|---|
|
|
| `/ui/api/compatibility?major=N` | JSON |
|
|
|
|
См. [Совместимость](compatibility.md) и [Покрытие API](api-coverage.md) для
|
|
полной разбивки Broadcom-universe в сравнении с реализованным.
|