REST API
HTTP-интерфейс для управления бакетами и объектами. API совместим с Amazon S3 в части подписи запросов (SigV4) и базовых операций над объектами.
Обзор
Базовый URL для всех запросов:
Все ответы возвращаются в формате JSON с заголовком Content-Type: application/json. Передача данных возможна по HTTPS (обязательно), HTTP-запросы отклоняются с кодом 400.
Аутентификация
Запросы аутентифицируются с помощью Bearer-токена. Ключи выпускаются в веб-консоли и имеют ограниченный набор разрешений и срок действия.
Каждый ключ привязан к проекту и может быть ограничен по:
- IP-адресам или диапазонам CIDR;
- разрешённым бакетам и операциям;
- сроку действия (по умолчанию 90 дней).
Пример запроса
Rate limits
Ограничения применяются на уровне ключа API и сбрасываются в скользящем окне.
| Операция | Лимит | Заголовок |
|---|---|---|
| Чтение (GET, HEAD) | 1200 req / мин | X-RateLimit-Remaining |
| Запись (PUT, POST, DELETE) | 300 req / мин | X-RateLimit-Remaining |
| Пакетная загрузка (multipart) | 10 параллельных | X-Concurrent-Uploads |
| Максимальный размер объекта | 5 ТБ | — |
При превышении лимита возвращается 429 Too Many Requests с заголовком Retry-After в секундах.
Бакеты
Список бакетов
Возвращает массив бакетов проекта с базовыми метаданными.
Создание бакета
Создаёт новый бакет. Имя должно быть уникальным в рамках проекта, 3–63 символа, только строчные латинские буквы, цифры и дефис.
Объекты
Загрузка объекта
Тело запроса — двоичные данные объекта. Поддерживается multipart-загрузка для объектов свыше 100 МБ.
Скачивание объекта
Возвращает двоичные данные объекта с заголовками ETag и Content-Type. Для приватных бакетов можно использовать подписанные URL.
Удаление объекта
Удаляет объект. Если для бакета включён Object Lock, операция возвращает 409 Conflict.
Коды ошибок
Ошибки возвращаются с соответствующим HTTP-статусом и объектом в теле ответа.
| HTTP | code | Описание |
|---|---|---|
| 400 | invalid_request | Некорректные параметры или тело запроса |
| 401 | unauthorized | Отсутствует или недействителен Bearer-токен |
| 403 | forbidden | Недостаточно прав для операции |
| 404 | not_found | Бакет или объект не найден |
| 409 | conflict | Конфликт состояния (например, Object Lock) |
| 413 | payload_too_large | Превышен максимальный размер объекта |
| 429 | rate_limited | Превышен лимит запросов, см. Retry-After |
| 500 | internal_error | Внутренняя ошибка сервиса |
| 503 | service_unavailable | Сервис временно недоступен (деградация/обслуживание) |