HTTP API
Маршруты
| Метод и путь | Назначение |
|---|---|
GET /v1/{profile}/file/{path} | Изображение из локального каталога профиля |
GET /v1/{profile}/remote?url=… | Изображение с разрешённого HTTPS-источника |
GET /upload/{path} | Alias, если он настроен в routes |
HEAD на маршруте изображения | Заголовки ответа без тела |
GET /health | Проверка процесса |
GET /ready | Проверка готовности |
/metrics и /license доступны на отдельном admin listener. Их не нужно публиковать через общедоступный прокси.
Выбор формата
curl --fail -H 'Accept: image/avif,image/webp' -D - http://127.0.0.1:8088/v1/bitrix/file/photo.jpg -o /tmp/zorka-image
Сервис учитывает веса q, wildcard и явные запреты форматов в Accept. При отсутствии заголовка выбирается WebP. При одинаковом качестве AVIF получает приоритет только при явном image/avif.
HTTPS-источник
curl --fail --get --data-urlencode 'url=https://images.example.com/photo.jpg' -H 'Accept: image/webp' http://127.0.0.1:8088/v1/remote/remote -o /tmp/zorka-remote.webp
Первый remote в пути — имя профиля из примера конфигурации, второй — тип маршрута. Хост источника должен быть разрешён этим профилем.
Версии файлов
Локальные file-маршруты принимают необязательный ?v=revision. Неизвестные и дублирующиеся параметры отклоняются. Путь декодируется один раз; + в пути остаётся плюсом.
Заголовки ответа
| Заголовок | Что показывает |
|---|---|
Content-Type | Фактический формат ответа |
Vary: Accept | Зависимость варианта от согласованного формата |
ETag | Валидатор представления |
X-Image-Cache | Уровень кэша или обход кэша |
X-Image-Profile | Выбранный профиль |
X-Image-Stored | Информация о сохранении результата |
X-Request-ID | Идентификатор для диагностики |
Поддерживаются If-None-Match и ответ 304. Настраивая внешний кэш, сохраняйте разделение вариантов по Accept.
Выдача оригинала
При неподдерживаемом преобразовании разрешённый клиентом проверенный оригинал может выдаваться с Cache-Control: no-store. В этом случае сохраняются его метаданные. Чтобы вместо оригинала получать ошибку, задайте http.fallback: error.
Fallback не обходит проверки повреждённых файлов, лимитов и запрещённых источников.