API · s5w

Клиентский API

Всё, что делает приложение-клиент: загрузка, файлы, папки и временные ссылки. Каждый запрос работает в одном бакете — в том, которому выдан токен.

Адрес http://<хост>:9090/v1Авторизация Bearer-токенФормат JSON

Спецификация и Postman

Весь клиентский API в двух готовых файлах — на русском и английском. Они лежат в репозитории S5W (docs/) и попадают сюда при каждой сборке документации, так что здесь всегда последняя версия.

OpenAPI 3.1.yaml

Спецификация всего клиентского API: операции, схемы, ошибки и примеры. Для Swagger, Redoc и генераторов SDK.

Русский94 КБ English81 КБ

В репозитории ↗

Postman-коллекция.postman_collection.json

Готовый сценарий: все запросы по порядку, примеры ответов и автопроверки. Импорт — и прогон кнопкой Run.

Русский186 КБ English166 КБ

В репозитории ↗

Импорт по ссылке

Postman (Import → Link), Swagger Editor (File → Import URL) и генераторы SDK принимают файл по адресу — «Ссылка для импорта» копирует прямой адрес в репозитории.

Разделы

/v1/files

Файлы

Загрузка одним запросом, список, переименование, перенос, удаление.

/v1/uploads

Загрузка частями

Большие файлы с продолжением после обрыва и дедупликацией по хешу.

/v1/folders

Папки

Видимость, срок хранения и политика кэша на папку.

/v1/…/link

Временные ссылки

Подписанные ссылки со сроком и лимитом скачиваний.

/o · /p · /t

Раздача

Три канала отдачи файлов, Range, ETag, ?download=1.

Обработка картинок

Размер, формат и качество — прямо при загрузке.

PHP SDK

Для PHP есть готовый клиент — S5W SDK (composer require flytachi/winter-sdk-s5w). Он сам выбирает между загрузкой одним запросом и частями, повторяет оборванные части, превращает ответы в объекты, а ошибки — в исключения по статусу.

Токены

Токен выпускается в панели (или через admin API) для конкретного бакета и передаётся в заголовке:

http

Authorization: Bearer s5w_…

У токена один из двух уровней доступа:

Уровень	В панели	Что можно
`BASIC`	только отдача	`GET /v1/check` и скачивание по токену `GET /p/{id}`
`FULL`	полный доступ	всё: файлы, загрузка, папки, ссылки

Токен можно ограничить сроком действия, отключить или перевыпустить (ротация) — старое значение после ротации перестаёт работать сразу.

Проверка токена

`GET /v1/check`

Проверяет токен и возвращает его бакет, уровень доступа и место. Доступен любому активному токену.

bash

curl -H "Authorization: Bearer <токен>" http://<хост>:9090/v1/check

Результат

json

{
  "bucket": { "id": "b554eae9-f8de-453f-8614-612069231234", "name": "media" },
  "access": { "id": 2, "name": "FULL" },
  "expiresAt": null,
  "bytes": { "quota": 104857600, "used": 3937, "free": 104853663 }
}

Ошибки

Ошибка — это код HTTP и JSON с полями code и message:

json

{ "code": 422, "message": "Uploaded data does not match the declared checksum" }

Если не прошла проверка параметров, добавляется errors — сообщения по полям:

json

{
  "code": 422,
  "message": "Validation failed",
  "errors": { "name": ["may contain letters, digits, space, dot, underscore, dash"] }
}

Код	Когда
`400`	Файл не передан; пустая или слишком маленькая часть загрузки
`401`	Токена нет или он неизвестен
`403`	Токен отключён, истёк или его уровня не хватает
`404`	Нет такого файла, загрузки или ссылки; в запросах `/v1/folders/{name}` — нет папки
`409`	Конфликт: папка уже есть, смещение части не совпало, загрузка не закончена, бакет не активен
`413`	Не хватает квоты бакета, часть больше 16 МиБ, тело больше 32 МиБ (такой ответ приходит без тела: его отсекает сервер)
`416`	Диапазон `Range` за пределами файла
`422`	Параметры не прошли проверку, указанной в `folder` папки нет, хеш не совпал, картинку нельзя обработать
`501`	На сервере нет обработки картинок или кодека для нужного формата
`507`	На диске сервера нет места

Пагинация

Списки принимают page (с 1) и limit (до 100, по умолчанию 25) и отвечают так:

json

{
  "meta": { "current": 1, "size": 25, "total": 42, "pages": 2, "previous": null, "next": 2 },
  "data": [ … ]
}

Исключение — GET /v1/files/{id}/links: он отдаёт массив без пагинации.

Удаление

Удаление отвечает 204 без тела. Исключение — DELETE /v1/links: 200 и { "epoch": … }.

Время

Все отметки времени в ответах — RFC 3339 (ISO 8601) с часовым поясом: 2026-11-08T17:10:44+00:00. Формат одинаков во всех ответах; стандартные библиотеки любого языка разбирают его без подготовки.

Значения перечислений

В запросах перечисления передаются числом: "retention": 3, "disposition": 1, "visibility": 1. Исключение — format: он строковый, "format": "WEBP". В ответах перечисления приходят объектом { "id": 3, "name": "MONTH" }.