Lesovik API Overview

Внутренний REST API для оркестрации сервисов инфраструктуры Lesovik. Все вызовы направляются через единый API Gateway, обеспечивающий TLS-терминацию, валидацию токенов, балансировку нагрузки и трейсинг запросов.

Base URL https://api.lesovik.tech/v1

Authentication

Все запросы к закрытым эндпоинтам должны содержать API-токен в заголовке Authorization с префиксом Bearer. Запросы без заголовка или с недействительным токеном отклоняются на уровне шлюза со статусом 401 Unauthorized.

HTTP Header Example HTTP

Authorization: Bearer lsk_live_9a7d3f82e1c4b588019a

Requests & Headers

API принимает и возвращает данные в формате UTF-8 JSON. Для запросов с телом (POST, PUT, PATCH) обязательно указание Content-Type: application/json.

Заголовок	Тип	Описание
`Content-Type`	String	Формат передаваемого тела (`application/json`).
`X-Request-Id`	String (UUID)	Опциональный сквозной идентификатор запроса для трассировки. Если опущен, генерируется шлюзом.
`X-Lesovik-Client`	String	Имя и версия вызывающего сервиса (например, `scheduler-daemon/2.1.0`).

Rate Limits

Шлюз применяет лимиты на основе скользящего окна (sliding window). При превышении квоты сервер возвращает статус 429 Too Many Requests.

Заголовок ответа	Описание
`X-RateLimit-Limit`	Максимальное количество запросов в текущем окне (по умолчанию: 120 req/min).
`X-RateLimit-Remaining`	Количество оставшихся запросов до сброса лимита.
`X-RateLimit-Reset`	Время сброса счетчика в формате Unix Epoch Timestamp (в секундах).

Errors

В случае ошибки API возвращает унифицированный JSON-объект ошибки с машиночитаемым кодом и описанием.

Standard Error Payload JSON (404 Not Found)

{
  "error": {
    "code": "resource_not_found",
    "message": "Resource with id 'res_8819a' does not exist.",
    "request_id": "req_c09fa810-75df"
  }
}

HTTP Status	Код ошибки	Причина
`400 Bad Request`	`invalid_payload`	Некорректная схема JSON или отсутствуют обязательные поля.
`401 Unauthorized`	`invalid_auth_token`	Токен авторизации отсутствует или недействителен.
`404 Not Found`	`resource_not_found`	Запрашиваемая сущность не найдена в кластере.
`429 Too Many Requests`	`rate_limit_exceeded`	Превышен лимит запросов за единицу времени.
`500 Internal Error`	`gateway_upstream_error`	Сбой внутреннего узла обработки.

Endpoints Reference

GET /v1/status

Проверка работоспособности сервиса, версии API и состояния подключения к базе данных.

Response Example 200 OK

{
  "status": "healthy",
  "version": "1.4.2",
  "cluster": "eu-west-node-03",
  "timestamp": 1774780800
}

GET /v1/resources

Возвращает список зарегистрированных ресурсов кластера с поддержкой курсорной пагинации.

Response Example 200 OK

{
  "data": [
    {
      "id": "res_8819a",
      "name": "cache-node-prod",
      "tier": "standard",
      "status": "active",
      "created_at": "2026-03-15T09:12:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

POST /v1/resources

Регистрация нового ресурса в системе.

Request Body JSON

{
  "name": "worker-pool-04",
  "tier": "high-compute",
  "tags": ["prod", "eu-west"]
}

Response Body 201 Created

{
  "id": "res_9921b",
  "name": "worker-pool-04",
  "tier": "high-compute",
  "status": "provisioning",
  "created_at": "2026-08-28T14:30:00Z"
}

GET /v1/events

Журнал системных событий и аудита изменений конфигурации.

Response Example 200 OK

{
  "events": [
    {
      "event_id": "evt_4011fa",
      "type": "resource.provisioned",
      "resource_id": "res_9921b",
      "actor": "srv_scheduler",
      "timestamp": "2026-08-28T14:31:02Z"
    }
  ]
}