Рекомендации по интеграции и работе с Widgets API

Aplaut старается держать свои API стабильными, но если API сломается целиком или частично, ваш сайт не должен этого заметить. Единственное, что могут увидеть покупатели, — временное исчезновение отзывов.

Почему запросов должно быть мало

Запрашивайте у Widgets API только те данные, которые показываете, и держите локальный кеш ответов со сроком жизни в несколько часов.

Рейтинги для листингов и блоков рекомендаций через Widgets API не запрашивайте: такой способ не оптимален ни для сайта, ни для API. Держите рейтинги в своей базе и обновляйте их через Platform API:

• регулярной выгрузкой: см. как выгрузить данные через Platform API;
• обходом каталога методом GET /scroll/products: см. как обойти записи через API. Курсор живёт 2 минуты, страницы можно запрашивать не чаще раза в 2 секунды, а начинать не больше 5 новых обходов в минуту. Без фильтра по дате обход отдаёт товары, обновлённые за последние 30 дней. Сводку отзывов товара берите через include=reviews_summary_item;
• точечно по вебхуку на событие пересчёта атрибутов товара recalculate_product_attributes: в теле вебхука уже есть рейтинг и число отзывов товара, см. справочник событий вебхуков.

В карточке товара рейтинг приходит вместе с отзывами из render.json.

Если виджет отзывов выводит отзывы на товары категории, карточку товара рядом с отзывом не нужно собирать отдельными запросами. Передайте в запрос include=product, и у каждого отзыва появится поле product: name, url, picture_url, price, available, rating, reviews_count, questions_count и external_id. Ссылки приходят без схемы, как и в остальных полях Widgets API. Неизвестные значения include API пропускает.

Сайт, мобильное приложение и эксперименты лучше направлять к Aplaut через один шлюз.

Почему ошибку лучше скрыть, чем повторять запрос

Повторные запросы не используйте. Если ответ пришёл с ошибкой, скройте блок с отзывами: для покупателя это и есть временное исчезновение контента, а не сломанная страница.

Паттерн circuit breaker в шлюзе или на устройствах почти обязателен. Он не даёт сайту зависать на таймаутах и не нагружает API, пока тот отвечает ошибками.

Успешному ответу тоже не стоит доверять вслепую. Во время аварии Aplaut не может гарантировать соблюдение контракта даже для ответа 200. Проверяйте входные данные и обрабатывайте ошибки как можно раньше, схема ответа — в справочнике Widgets API.

Какие сбои должен выдерживать сайт

Устойчивая интеграция открывает страницу и скрывает только отзывы в каждом из сценариев:

• Widgets API отвечает ошибками, например 502, 503, 504 или 429;
• ответ идёт секунды или десятки секунд;
• API не отвечает совсем, например доступ с ваших IP закрыт;
• домен API не резолвится;
• ответ 200, но данные некорректные;
• всё перечисленное повторяется несколько дней подряд.