Подключение

Пять шагов. Первые три делает оператор сервиса, последние два — вы у себя.

1. Домен

Выберите поддомен, с которого будут отдаваться файлы — например img.вашдомен, — и заведите на него A-запись, которую даст оператор. Домен объявляется каноническим: именно из него сервис собирает адреса в ответах.

Доменов у арендатора может быть сколько угодно, но канонический ровно один. Иначе один файл получит два адреса, а значит и два кеша, и два скачивания на телефоне читателя.

Свой домен можно и не подключать: тогда файлы отдаются с общего keepix.cloud. Обе дороги работают одинаково.

2. Виды и варианты

Вид (kind) — это то, к какому роду относится файл: prodimg для каталожных картинок, review для фото отзывов, и так далее. Для каждого вида объявляется, какие варианты ему полагаются.

Заодно назначаются потолки: размер одного файла, число загрузок в минуту и общий объём.

3. Ключи подписи

Вы получаете два ключа — идентификатор и секрет к каждому. Два, а не один, чтобы смена ключа не была простоем: новый вводится в дело, пока старый ещё действует, и только потом гасится.

Секрет показывается один раз. Храните его там же, где остальные секреты проекта, и никогда не передавайте в командной строке.

4. Первый файл

Отправьте оригинал и сохраните адреса из ответа рядом с записью, к которой файл относится.

POST /api/v1/put?kind=prodimg&key=<ваш идентификатор>&variants=card,full

Если у вас уже накоплены готовые копии — их можно перенести без перекодирования через put-variant. Перекодировать готовое второй раз значит потерять качество на ровном месте.

Одно место в коде, а не четыре. Подставляйте сохранённый адрес в одной функции, через которую ходят все витрины. Если условие «локально или на сервисе» размазать по четырём страницам, они разойдутся на первой же правке — и разойдутся молча.

5. Сторож

Заведите проверку, которая ходит тем же путём, что и витрина: спрашивает у сервиса известный объект и сверяет четыре вещи — ответ 200, тип содержимого, ненулевую длину и что адрес совпал с тем, который записан у вас.

Последнее важнее остальных. Если раскладка изменится, а вы не заметите, картинки исчезнут молча: страница отрисуется, а на месте товара будет дыра.

И проверьте сторожа сломав что-нибудь нарочно — подмените записанный адрес и убедитесь, что он ругается. Сторож, который никогда не срабатывал, — это не сторож, а строчка в конфиге.

Что делать, если запись потерялась

Спросить, а не угадать:

GET  /api/v1/resolve?kind=prodimg&key=48120
POST /api/v1/resolve-batch     {"kind":"prodimg","keys":["1","2","…"]}   ← до 1000 ключей

Сервис на то и хранит адреса, чтобы их не приходилось выводить по правилу.