a.tolmachev
179 lines
6.1 KiB
Markdown
179 lines
6.1 KiB
Markdown
# Admin API
|
|
|
|
## 1. Назначение документа
|
|
|
|
Этот документ фиксирует целевые HTTP-контракты административного API, через которое UI управляет workspace, operations, agents, platform access и observability.
|
|
|
|
## 2. Общие правила API
|
|
|
|
- все payload по умолчанию в `JSON`;
|
|
- import/export конфигурации используют `YAML`;
|
|
- все основные ресурсы являются `workspace-scoped`;
|
|
- версии operation и agent адресуются явно;
|
|
- published operation и published agent - ссылки на конкретные version;
|
|
- ошибки валидации возвращаются отдельно от transport errors.
|
|
|
|
Базовый префикс:
|
|
|
|
```text
|
|
/api/admin
|
|
```
|
|
|
|
## 3. Основные ресурсы
|
|
|
|
- `workspaces`
|
|
- `memberships`
|
|
- `invitations`
|
|
- `operations`
|
|
- `auth-profiles`
|
|
- `agents`
|
|
- `platform-api-keys`
|
|
- `logs`
|
|
- `usage`
|
|
- `samples`
|
|
- `descriptors`
|
|
- `config import/export`
|
|
|
|
## 4. Workspace-scoped routing
|
|
|
|
Канонический префикс для UI-driven сценариев:
|
|
|
|
```text
|
|
/api/admin/workspaces/{workspace_id}
|
|
```
|
|
|
|
## 5. Группы endpoints
|
|
|
|
### 5.1. Workspaces and members
|
|
|
|
- `GET /api/admin/workspaces`
|
|
- `POST /api/admin/workspaces`
|
|
- `GET /api/admin/workspaces/{workspace_id}`
|
|
- `PATCH /api/admin/workspaces/{workspace_id}`
|
|
- `GET /api/admin/workspaces/{workspace_id}/members`
|
|
- `POST /api/admin/workspaces/{workspace_id}/invitations`
|
|
- `DELETE /api/admin/workspaces/{workspace_id}/invitations/{invitation_id}`
|
|
|
|
### 5.2. Operations
|
|
|
|
- `GET /api/admin/workspaces/{workspace_id}/operations`
|
|
- `POST /api/admin/workspaces/{workspace_id}/operations`
|
|
- `GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}`
|
|
- `PATCH /api/admin/workspaces/{workspace_id}/operations/{operation_id}`
|
|
- `DELETE /api/admin/workspaces/{workspace_id}/operations/{operation_id}`
|
|
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions`
|
|
- `GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions/{version}`
|
|
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/publish`
|
|
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/archive`
|
|
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/test-runs`
|
|
- `GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}/export`
|
|
- `POST /api/admin/workspaces/{workspace_id}/operations/import`
|
|
|
|
### 5.3. Samples and descriptors
|
|
|
|
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/input-json`
|
|
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/output-json`
|
|
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/drafts/generate`
|
|
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/descriptors/proto`
|
|
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/descriptors/descriptor-set`
|
|
- `GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}/grpc/services`
|
|
|
|
### 5.4. Upstream auth profiles
|
|
|
|
- `GET /api/admin/workspaces/{workspace_id}/auth-profiles`
|
|
- `POST /api/admin/workspaces/{workspace_id}/auth-profiles`
|
|
- `GET /api/admin/workspaces/{workspace_id}/auth-profiles/{auth_profile_id}`
|
|
- `PATCH /api/admin/workspaces/{workspace_id}/auth-profiles/{auth_profile_id}`
|
|
- `DELETE /api/admin/workspaces/{workspace_id}/auth-profiles/{auth_profile_id}`
|
|
|
|
### 5.5. Agents
|
|
|
|
- `GET /api/admin/workspaces/{workspace_id}/agents`
|
|
- `POST /api/admin/workspaces/{workspace_id}/agents`
|
|
- `GET /api/admin/workspaces/{workspace_id}/agents/{agent_id}`
|
|
- `PATCH /api/admin/workspaces/{workspace_id}/agents/{agent_id}`
|
|
- `DELETE /api/admin/workspaces/{workspace_id}/agents/{agent_id}`
|
|
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/versions`
|
|
- `GET /api/admin/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}`
|
|
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/publish`
|
|
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings`
|
|
- `DELETE /api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings/{operation_id}`
|
|
|
|
### 5.6. Platform API keys
|
|
|
|
- `GET /api/admin/workspaces/{workspace_id}/platform-api-keys`
|
|
- `POST /api/admin/workspaces/{workspace_id}/platform-api-keys`
|
|
- `POST /api/admin/workspaces/{workspace_id}/platform-api-keys/{key_id}/revoke`
|
|
- `DELETE /api/admin/workspaces/{workspace_id}/platform-api-keys/{key_id}`
|
|
|
|
### 5.7. Observability
|
|
|
|
- `GET /api/admin/workspaces/{workspace_id}/logs`
|
|
- `GET /api/admin/workspaces/{workspace_id}/logs/{log_id}`
|
|
- `GET /api/admin/workspaces/{workspace_id}/usage`
|
|
- `GET /api/admin/workspaces/{workspace_id}/usage/operations/{operation_id}`
|
|
- `GET /api/admin/workspaces/{workspace_id}/usage/agents/{agent_id}`
|
|
|
|
## 6. Page-to-endpoint mapping
|
|
|
|
### Operations catalog
|
|
|
|
Нужны:
|
|
|
|
- список операций;
|
|
- удаление операции;
|
|
- edit/open operation;
|
|
- publish/archive;
|
|
- usage summary для карточек и фильтров.
|
|
|
|
### Wizard
|
|
|
|
Нужны:
|
|
|
|
- create/update version;
|
|
- test run;
|
|
- samples;
|
|
- draft generation;
|
|
- gRPC descriptor upload и discovery.
|
|
|
|
Детальные DTO и response shapes для экранов `Operations` и `Wizard` зафиксированы отдельно в:
|
|
|
|
- `docs/operations-workspace-contracts.md`
|
|
|
|
### Agents
|
|
|
|
Нужны:
|
|
|
|
- CRUD агентов;
|
|
- bindings к operations;
|
|
- publish agent;
|
|
- выдача MCP endpoint metadata.
|
|
|
|
### API Keys
|
|
|
|
Нужны:
|
|
|
|
- list/create/revoke/delete platform API keys;
|
|
- one-time reveal значения ключа при создании.
|
|
|
|
### Logs
|
|
|
|
Нужны:
|
|
|
|
- list logs с фильтрами;
|
|
- log detail;
|
|
- polling или live refresh strategy.
|
|
|
|
### Usage
|
|
|
|
Нужны:
|
|
|
|
- агрегаты по периодам;
|
|
- breakdown по operation;
|
|
- breakdown по agent;
|
|
- CSV export.
|
|
|
|
## 7. Принцип совместимости
|
|
|
|
Если UI расходится с текущим backend, приоритет отдается целевой продуктовой модели, но конфликт должен быть явно разобран в `docs/as-is-to-be.md` до начала реализации.
|