Перейти к основному содержимому

Обновление схемы API — 10 августа 2026

Корневой swagger.json заменён последним экспортом от команды бэкенда. Контракт теперь называется ZennoHosting API вместо ZennoHosting API (DEV). Базовый адрес и схема авторизации OAuth2 не изменились. Число операций уменьшилось с 76 до 72.

Добавленные эндпоинты​

  • Лимиты ресурсов: GET /limits возвращает квоты пользователя — проекты, токены доступа, сети, публичные адреса и суммарные CPU, RAM и диск по всем машинам — каждую с лимитом, текущим потреблением и остатком.
  • Ограничения длины имён: GET /limits/name-lengths возвращает максимальные длины имён проекта, сети, машины, SSH-ключа и токена доступа, а также длину значения публичного SSH-ключа. Это правила валидации, а не квоты.
  • Счётчики состояний машин: GET /projects/{projectId}/vms/state-counts возвращает число машин проекта с разбивкой по статусу жизненного цикла и по состоянию питания; счётчики считаются на сервере.

Оба эндпоинта лимитов собраны под новым тегом Limits.

Удалённые эндпоинты​

  • Административные saga-эндпоинты /admin/sagas — список, детали, finalize и force-compensate — анонсированные в обновлении от 14 июля 2026. Вместе с ними ушли их страницы справочника, схемы и страницы параметров saga-type, states и correlation-id.
  • Платёжные эндпоинты /payments. Они и раньше исключались из документируемой поверхности через excludedTags, поэтому на сайте ничего не изменилось.

Изменения схем, важные для клиентов​

  • Новое поле status у машин, сетей и публичных адресов. Enum ResourceStatus — creating, active, updating, deleting, failed — теперь рекомендуемый способ показывать состояние ресурса. Прежняя пара operation/operationStatus сохранена только для обратной совместимости.
  • OperationResponse.lastError заменено на failureCode с типом нового enum OperationFailureCode: insufficientCapacity, timeout, internal.
  • Новый тип ApiProblemDetails добавляет к телу ошибки поле code — устойчивый машиночитаемый признак конкретной ошибки. Сейчас он объявлен ровно у одного ответа: 409 при создании машины, где code равен insufficientCapacity. Все остальные ответы об ошибке по-прежнему используют базовый тип без code.
  • У ConfigurationResponse появились availability и maxCount — справочные признаки того, есть ли сейчас мощности под конфигурацию.
  • У RebuildVmRequest появилось deleteBackups со значением по умолчанию false.
  • У BackupResponse появилось sourceImageId; для копий, созданных до появления поля, оно равно null.
  • У NetworkResponse, PublicIpResponse и VmResponse появилось status.
  • ProjectResponse.vmCount помечено устаревшим в пользу resourceCounts.vms.
  • Десять новых схем: ApiProblemDetails, OperationFailureCode, ResourceLimitsResponse, ResourceNameLengthLimitsResponse, ResourceQuotaResponse, ResourceStatus, VmPowerStateCountsResponse, VmResourceLimitsResponse, VmStateCountsResponse, VmStatusCountsResponse. Ни одна схема не удалена.

Ломающие изменения и что делать​

  • Клиенты, читавшие lastError у операции, должны перейти на failureCode: старое поле удалено, а не помечено устаревшим.
  • Любой инструмент, вызывающий /admin/sagas, получит 404. Замены в этом контракте нет.
  • Для отображения состояния ресурса переходите с operation/operationStatus на status. Учтите: status равен active и после неудачной операции, если сбой обработан штатно — запуск, остановка, перезагрузка или изменение конфигурации, которые можно просто повторить, оставляют ресурс активным. Об исходе операции судите по её записи, а не по состоянию ресурса.
  • Требование OAuth2 не изменилось. Перегенерируйте типы API перед обновлением.

Что сделано в документации вместе с этим обновлением​

  • Новые авторские страницы: Лимиты и квоты, Ошибки API и Инвентаризация и мониторинг.
  • Статусы и жизненный цикл переписана вокруг поля status; там же перечислены поля, оставленные только для совместимости.
  • В гайды добавлены availability/maxCount, sourceImageId и deleteBackups.
  • Подписи операций в справочнике теперь короткие, а не целые предложения; внутренние имена типов .NET больше не попадают в публичные описания.

Известные пробелы контракта​

Переданы команде бэкенда, здесь зафиксированы как есть:

  • Регистр значений enum непоследователен: ResourceStatus и OperationFailureCode в нижнем camelCase (creating, internal), а ApiOperationStatus, VmBootStatus и ResourceOperation — в PascalCase (Queued, Running, Provision).
  • Описание OperationFailureCode ссылается на значение по умолчанию Internal, которого в enum нет; фактическое значение — internal.
  • ApiProblemDetails подключён к одному ответу, поэтому полагаться на code во всём API пока нельзя.
  • GET .../vms/{vmId}/metrics возвращает предопределённые тестовые данные, а POST .../vms/{vmId}/resize всегда отвечает 503 Service Unavailable. Оба остаются в справочнике, но исключены из авторских гайдов.