Рецепты API и CLI для Корзины

Готовые к копированию примеры для каждого эндпоинта Корзины. В каждом
разделе приведён вызов cURL и эквивалентная команда CLI.

О URL в примерах: все примеры используют http://localhost:5770.
Замените адрес, если ваш инстанс Mockarty работает на другом хосте. См.
Советы и полезные функции.

Связанные страницы: Корзина · Руководство по
CLI · Справочник API

Аутентификация

Все эндпоинты требуют API-токен в заголовке X-API-Key. Токены
выпускаются в Настройки → API-токены (или POST /api/v1/auth/tokens) с
ролью, привязанной к пространству имён.

export MOCKARTY_URL=http://localhost:5770
export MOCKARTY_API_TOKEN=mk_7_...
export MOCKARTY_NAMESPACE=default

Работа из кода

Корзина доступна по REST и из CLI. SDK для Go, Python и Java намеренно её не
оборачивают: они покрывают то, что нужно тесту или CI-задаче, а очистка корзины
namespace’а — операторское действие. Используйте curl (примеры ниже) или
mockarty-cli trash … из скрипта.

Карта эндпоинтов

Список мягко удалённых элементов

Фильтры: type=mock,store, q=substring, cascade=<id>,
closed_by=<email>, from=<RFC3339>, to=<RFC3339>, limit, offset.

cURL

curl -s -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash?type=mock,store&limit=50"

CLI

mockarty-cli trash list --type mock,store --limit 50
mockarty-cli trash list --admin                       # по всей платформе

Ответ:

{
  "items": [
    {
      "id": "mock-abc",
      "name": "users",
      "namespace": "default",
      "entity_type": "mock",
      "closed_at": "2026-04-19T12:00:00Z",
      "closed_by": "alice@example.com",
      "cascade_group_id": "11111111-1111-4111-8111-111111111111",
      "restore_available": true
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

total учитывает все подходящие элементы среди всех типов ресурсов.
Параметры offset и limit позволяют получить следующие страницы, включая
элементы после первых 500 записей одного типа.

Сводка (счётчики для бейджей)

cURL

curl -s -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash/summary"

CLI

mockarty-cli trash summary
mockarty-cli trash summary --admin

Настройки ретеншна

cURL

# Прочитать
curl -s -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash/settings"

# Upsert
curl -s -X PUT -H "Content-Type: application/json" -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash/settings" \
  -d '{"retention_days": 14, "enabled": true}'

# Глобальные значения (только админ)
curl -s -X PUT -H "Content-Type: application/json" -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/admin/trash/settings/global" \
  -d '{"retention_days": 30, "enabled": true}'

CLI

mockarty-cli trash settings get
mockarty-cli trash settings set --retention-days 14 --enabled
mockarty-cli trash settings set --global --retention-days 30 --enabled

Восстановить одну каскадную группу

cURL

curl -s -X POST -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash/restore-cascade/11111111-1111-4111-8111-111111111111"

CLI

mockarty-cli trash restore 11111111-1111-4111-8111-111111111111

Ответ (camelCase, формат одиночного восстановления):

{ "cascadeGroupId": "11111111-1111-4111-8111-111111111111", "restoredCount": 4 }

Восстановление затрагивает только записи, которые всё ещё принадлежат этой
каскадной группе. Если запись уже восстановили и удалили снова, повторный
запрос для прежней группы оставит новое удаление в Корзине. Для восстановления
используйте текущую запись Корзины.

Для восстановления удалённой задачи или доски задач её проект должен быть
активен. Если проект находится в корзине, сначала восстановите проект. Иначе
восстановление задачи или доски вернёт конфликт и оставит её в корзине.

Массовое восстановление

cURL

curl -s -X POST -H "Content-Type: application/json" -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash/restore" \
  -d '{"cascade_group_ids": ["11111111-1111-4111-8111-111111111111", "22222222-2222-4222-8222-222222222222"], "reason": "откат"}'

CLI

mockarty-cli trash restore 11111111-1111-4111-8111-111111111111,22222222-2222-4222-8222-222222222222 --reason "откат"

Ответ (конверт 207):

{
  "restored":  [{ "cascade_group_id": "11111111-1111-4111-8111-111111111111", "entity_type": "mock", "restored_count": 4 }],
  "failed":    [{ "cascade_group_id": "22222222-2222-4222-8222-222222222222", "error": "parent container still deleted" }],
  "not_found": []
}

У каждой группы с ошибкой есть поле error. Ожидаемые продуктовые отказы
содержат понятное сообщение и могут иметь стабильный код reason. При
внутреннем сбое хранилища возвращается recycle bin operation failed;
перед повтором проверьте состояние сервиса.

Массовая очистка (НЕОБРАТИМО)

Сервер требует точной фразы "I understand this is permanent" в поле
confirmation. SDK и CLI проверяют её локально, поэтому неверный
запрос до сервера не доходит.

cURL

curl -s -X POST -H "Content-Type: application/json" -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash/purge" \
  -d '{
    "cascade_group_ids": ["11111111-1111-4111-8111-111111111111"],
    "confirmation": "I understand this is permanent",
    "reason": "GDPR запрос"
  }'

CLI

# интерактивно (запрашивает фразу)
mockarty-cli trash purge 11111111-1111-4111-8111-111111111111

# неинтерактивно
mockarty-cli trash purge 11111111-1111-4111-8111-111111111111 --yes --reason "GDPR запрос"

Ответ (конверт 207):

{
  "purged":    [{ "cascade_group_id": "11111111-1111-4111-8111-111111111111", "entity_type": "mock", "rows_deleted": 7 }],
  "failed":    [],
  "not_found": []
}

При внутреннем сбое хранилища ошибка группы содержит общее сообщение
recycle bin operation failed. Группа остаётся в корзине.

Полная очистка корзины (НЕОБРАТИМО)

purge-all навсегда удаляет все мягко удалённые элементы в области
видимости. В отличие от purge, список id не нужен — сервер сам
находит все закрытые cascade-группы и удаляет их пакетами, пока корзина
не опустеет, поэтому команда масштабируется на корзины с десятками тысяч
элементов. Требует ту же подтверждающую фразу, что и purge.

cURL

curl -s -X POST -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirmation":"I understand this is permanent","reason":"очистка перед релизом"}' \
  "$MOCKARTY_URL/api/v1/namespaces/team-orders/trash/purge-all"

CLI

mockarty-cli trash empty --namespace team-orders --yes --reason "очистка перед релизом"

Ответ:

{
  "rows_deleted": 18342,
  "groups_purged": 7561,
  "groups_failed": 0,
  "batches_run": 16,
  "truncated": false
}

truncated: true означает, что корзина была настолько большой, что
сработал предохранительный лимит до полной очистки — запустите команду
ещё раз, чтобы завершить.
Если поиск или обработка группы завершаются ошибкой, first_error содержит
публичную причину; внутренний сбой хранилища обозначается
recycle bin operation failed.

Ручной тик ретеншна (только админ)

Синхронно запускает планировщик ретеншна по всем пространствам. Полезно
для тестов или чтобы удостовериться, что планировщик работает.
В кластере отправляйте запрос лидеру. Другой узел отвечает HTTP 503 с
code: "not_leader"; повторите запрос на лидере. Ручной и плановый тики
на одном узле выполняются последовательно.

cURL

curl -s -X POST -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/admin/trash/purge-now"

CLI

mockarty-cli trash purge-now

Ответ:

{ "status": "ok", "purged_total": 123, "namespaces_scanned": 4 }

Если чтение или очистка хотя бы одного ресурса завершились ошибкой, запрос
возвращает HTTP 500. Часть строк могла быть уже удалена: проверьте корзину и
повторите операцию после устранения ошибки. При достижении лимита времени
возвращается status: "partial" с числом уже удалённых строк.

Ошибочные ответы

См. также

• Корзина — концептуальное руководство, UI и
  матрица RBAC.
• Руководство по CLI — полный справочник
  mockarty-cli trash ….
• Руководство по SDK — установка и общие идиомы
  SDK.