API v1 · стабильная версия

Документация API

Полная спецификация S3-совместимого API YuriCloud: аутентификация, эндпоинты, управление bucket'ами, загрузка объектов и резервное копирование. Базовый URL: https://api.cloud.yuriyuri.ru/v1

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

YuriCloud использует Signature V4 — ту же схему подписи запросов, что и AWS S3. Каждый запрос подписывается секретным ключом access_secret, привязанным к вашему сервисному аккаунту. Получить ключи можно в личном кабинете.

В заголовках каждого запроса должны присутствовать:

Authorization — подпись AWS4-HMAC-SHA256
x-amz-date — временная метка в формате ISO 8601 (UTC)
Host — домен регионального эндпоинта

# Пример формирования подписанного запроса GET / HTTP/1.1 Host: s3.eu.cloud.yuriyuri.ru x-amz-date: 20260112T101530Z Authorization: AWS4-HMAC-SHA256 Credential=YL_ACCESS_KEY/20260112/eu/s3/aws4_request, SignedHeaders=host;x-amz-date, Signature=a3f2...e91c

Для упрощения работы мы рекомендуем использовать aws-cli, s3cmd или rclone — все они совместимы с YuriCloud из коробки.

2. S3 API Endpoints

YuriCloud развёрнут в нескольких регионах. Выбирайте ближайший регион для минимальной задержки. Все эндпоинты поддерживают HTTPS (TLS 1.2+).

Регион	Код	Эндпоинт	Latency (p50)
Европа (Франкфурт)	`eu`	`s3.eu.cloud.yuriyuri.ru`	~28 мс
Россия (Москва)	`ru`	`s3.ru.cloud.yuriyuri.ru`	~12 мс
Россия (Санкт-Петербург)	`ru-2`	`s3.ru2.cloud.yuriyuri.ru`	~18 мс
Азия (Дубай)	`ae`	`s3.ae.cloud.yuriyuri.ru`	~46 мс

Эндпоинт объекта формируется по шаблону:

# Шаблон https://<bucket>.s3.<region>.cloud.yuriyuri.ru/<key> # Пример https://uploads.s3.eu.cloud.yuriyuri.ru/2026/01/report.csv

3. Управление Bucket'ами

Bucket — корневой контейнер для объектов. Имя должно быть глобально уникальным, соответствовать DNS-именам (3–63 символа, строчные буквы, цифры, дефисы). Создание, удаление и настройка lifecycle выполняются через стандартные S3-вызовы.

# Создание bucket в регионе EU curl -X PUT https://s3.eu.cloud.yuriyuri.ru/my-bucket \ -H "Authorization: AWS4-HMAC-SHA256 ..." \ -H "x-amz-date: 20260112T101530Z" \ -H "Content-Length: 0" # HTTP/1.1 200 OK Location: /my-bucket

Поддерживаемые операции с bucket:

Метод	Путь	Описание
`PUT`	`/{bucket}`	Создать bucket
`DELETE`	`/{bucket}`	Удалить пустой bucket
`GET`	`/`	Список всех bucket'ов аккаунта
`PUT`	`/{bucket}?versioning`	Включить версионирование
`PUT`	`/{bucket}?lifecycle`	Настроить lifecycle-политику
`GET`	`/{bucket}?location`	Получить регион bucket

4. Загрузка объектов

Объекты загружаются одним PUT-запросом (до 5 ГБ) или multipart upload (до 5 ТБ, части по 5–100 МБ). После загрузки объект сразу доступен для чтения и реплицируется в 3 зоны доступности.

# Простая загрузка объекта curl -X PUT https://s3.eu.cloud.yuriyuri.ru/my-bucket/photo.jpg \ -H "Authorization: AWS4-HMAC-SHA256 ..." \ -H "x-amz-date: 20260112T101530Z" \ -H "Content-Type: image/jpeg" \ -H "x-amz-server-side-encryption: AES256" \ --data-binary @photo.jpg # HTTP/1.1 200 OK ETag: "d41d8cd98f00b204e9800998ecf8427e" x-amz-version-id: 3L4s5c8H7K2p1qR9

Опциональные заголовки при загрузке:

x-amz-server-side-encryption — AES256 (по умолчанию) или aws:kms
x-amz-meta-* — пользовательские метаданные (до 2 КБ)
Cache-Control, Content-Disposition — стандартные HTTP-заголовки
x-amz-storage-class — STANDARD, STANDARD_IA, GLACIER

5. Backup API

Backup API — собственное расширение YuriCloud для управления политиками резервного копирования. Поддерживаются инкрементальные снимки, шифрование, расписание по cron и кросс-региональная репликация.

# Создание политики бэкапа POST /v1/backup/policies HTTP/1.1 Host: api.cloud.yuriyuri.ru Content-Type: application/json { "name": "nightly-snapshot", "source_bucket": "my-bucket", "target_region": "ru", "schedule": "0 2 * * *", "retention": { "days": 30, "keep_weekly": 12 }, "encryption": "AES256", "incremental": true } # HTTP/1.1 201 Created { "policy_id": "pol_8f3a9d2c", "status": "active" }

Методы Backup API:

Метод	Путь	Описание
`POST`	`/v1/backup/policies`	Создать политику
`GET`	`/v1/backup/policies`	Список политик
`POST`	`/v1/backup/run/{policy_id}`	Запустить вне расписания
`GET`	`/v1/backup/snapshots`	Список снимков
`POST`	`/v1/backup/restore/{snapshot_id}`	Восстановить в bucket

6. Лимиты и квоты

Базовые лимиты можно повысить в личном кабинете или через запрос в поддержку. Лимиты применяются per-region, чтобы предотвратить каскадные сбои.

Параметр	White Lily	Pure Cloud	Enterprise
Bucket'ов на аккаунт	2	20	безлимит
Запросов в секунду	500	3 000	50 000
Размер объекта (single PUT)	5 ГБ	5 ГБ	5 ГБ
Multipart upload	5 ТБ	5 ТБ	5 ТБ
Одновременных соединений	50	500	10 000
Retention snapshots	30 дней	90 дней	1 год+

При превышении лимита API вернёт 503 SlowDown с заголовком Retry-After. Рекомендуем использовать экспоненциальную задержку с джиттером.