REST API

HTTP-интерфейс для управления бакетами и объектами. API совместим с Amazon S3 в части подписи запросов (SigV4) и базовых операций над объектами.

Обзор

Базовый URL для всех запросов:

https://api.skystorage.duckdns.org/v1

Все ответы возвращаются в формате JSON с заголовком Content-Type: application/json. Передача данных возможна по HTTPS (обязательно), HTTP-запросы отклоняются с кодом 400.

Версионирование. Текущая стабильная версия — v1. При выпуске несовместимых изменений будет доступен новый префикс /v2, при этом v1 поддерживается не менее 12 месяцев.

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

Запросы аутентифицируются с помощью Bearer-токена. Ключи выпускаются в веб-консоли и имеют ограниченный набор разрешений и срок действия.

Authorization: Bearer sk_live_9f3c8a2e7b1d4c6f0a5e8d3b7c2a1f4e

Каждый ключ привязан к проекту и может быть ограничен по:

  • IP-адресам или диапазонам CIDR;
  • разрешённым бакетам и операциям;
  • сроку действия (по умолчанию 90 дней).

Пример запроса

# Список бакетов проекта curl -X GET "https://api.skystorage.duckdns.org/v1/buckets" \ -H "Authorization: Bearer $SKY_TOKEN"

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 в секундах.

Бакеты

Список бакетов

GET/v1/buckets

Возвращает массив бакетов проекта с базовыми метаданными.

{ "buckets": [ { "name": "prod-backups", "region": "eu-central-1", "objects": 128442, "size_bytes": 84739201982, "created_at": "2024-11-02T09:14:00Z" } ] }

Создание бакета

POST/v1/buckets

Создаёт новый бакет. Имя должно быть уникальным в рамках проекта, 3–63 символа, только строчные латинские буквы, цифры и дефис.

curl -X POST "https://api.skystorage.duckdns.org/v1/buckets" \ -H "Authorization: Bearer $SKY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"prod-assets","region":"eu-central-1"}'
{ "name": "prod-assets", "region": "eu-central-1", "created_at": "2025-04-12T11:02:34Z" }

Объекты

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

PUT/v1/objects/{bucket}/{key}

Тело запроса — двоичные данные объекта. Поддерживается multipart-загрузка для объектов свыше 100 МБ.

curl -X PUT "https://api.skystorage.duckdns.org/v1/objects/prod-assets/logo.svg" \ -H "Authorization: Bearer $SKY_TOKEN" \ -H "Content-Type: image/svg+xml" \ --data-binary @./logo.svg

Скачивание объекта

GET/v1/objects/{bucket}/{key}

Возвращает двоичные данные объекта с заголовками ETag и Content-Type. Для приватных бакетов можно использовать подписанные URL.

Удаление объекта

DELETE/v1/objects/{bucket}/{key}

Удаляет объект. Если для бакета включён Object Lock, операция возвращает 409 Conflict.

Коды ошибок

Ошибки возвращаются с соответствующим HTTP-статусом и объектом в теле ответа.

{ "error": { "code": "not_found", "message": "Object does not exist", "request_id": "req_7f3c8a2e7b1d4c6f" } }
HTTPcodeОписание
400invalid_requestНекорректные параметры или тело запроса
401unauthorizedОтсутствует или недействителен Bearer-токен
403forbiddenНедостаточно прав для операции
404not_foundБакет или объект не найден
409conflictКонфликт состояния (например, Object Lock)
413payload_too_largeПревышен максимальный размер объекта
429rate_limitedПревышен лимит запросов, см. Retry-After
500internal_errorВнутренняя ошибка сервиса
503service_unavailableСервис временно недоступен (деградация/обслуживание)