api-crash-dog

Сервис раннего обнаружения изменений в контракте внешних API — до того, как они незаметно сломают продакшен-скрипты.

Проблема

Инструменты для работы с маркетплейсами и сервисами (Wildberries, Ozon, МойСклад, Деловые Линии, MOEX) зависят от чужих API. Площадки меняют контракт без предупреждения: новое обязательное поле, устаревший метод, изменённая структура ответа. Скрипты, построенные на этих API, ломаются тихо — проблема обнаруживается постфактум, когда уже что-то не сработало.

Идея

Название отсылает к собакам, обученным заранее обнаруживать угрозу, а не реагировать на уже случившееся: инструмент отслеживает документацию и контракт площадок, сообщает о конкретном изменении и по нему можно прогнать тесты существующих скриптов до того, как поломка попадёт в продакшен.

Близкое есть в части Keys проекта wb-api-workbench — там проверяется живость и права собственных ключей доступа. Предмет проверки здесь другой — сам внешний API, его документация и схема.

Архитектура

Решение по каждой площадке принимается отдельно, в зависимости от того, что она публикует:

Структурированный дифф — есть машиночитаемый контракт (файл спецификации или самоописывающийся API), сравниваются напрямую

• Wildberries — dev.wildberries.ru — вручную: портал закрыт антибот-защитой (JS-проверка), автоматический запрос получает 498 без выполнения JS. Спека обновляется руками, см. ниже
• МойСклад — dev.moysklad.ru/doc/api/remap/1.2 — автоматически: отслеживается SHA последнего коммита в GitHub-репозитории спеки
• MOEX ISS — iss.moex.com/iss/reference — автоматически: спека берётся с iss.moex.com/iss/engines.json

Текстовый дифф — формального контракта нет, сравнивается содержимое страницы документации

• Ozon Seller — docs.ozon.ru/api/seller — вручную: та же история, что и с Wildberries — за антибот-редиректом стоит JS-челлендж (похоже на Qrator), автоматический клиент до страницы не доходит
• Lamoda (Seller v2) — academy.lamoda.ru — автоматически: страница документации скачивается напрямую
• Деловые Линии — dev.dellin.ru/api — под вопросом: страница отвечает 401 Unauthorized, похоже на требование логина на портал разработчика — уточняется

Что значит «вручную»

Для площадок за антибот-защитой автоматический HTTP-запрос (httpx, и обычный curl — тоже) не проходит ни при каком наборе заголовков: нужен реальный браузер, который выполнит JS-проверку. Вместо того чтобы городить headless-браузер, такие площадки подключены через spec_source: local в platforms.yaml — снэпшот читается не по сети, а из файла на диске в manual_snapshots/. Файл обновляется человеком: открыть страницу в браузере (сессия там и проходит проверку), сохранить содержимое как есть поверх старого файла. crashdog дальше сравнивает этот файл с предыдущей версией точно так же, как сравнивал бы содержимое, полученное по сети — разница только в том, кто именно скачивает файл, автоматика или человек. Если находка не появляется сама по расписанию — это ожидаемо, обновление файла не автоматизировано.

Разработка идёт в две фазы:

• Фаза 1. Логика без веб-слоя: снэпшот контракта → сравнение с предыдущим → уведомление при разнице → запись находки в SQLite. Веб-интерфейс на этом этапе не нужен — можно проверить логику запуском по расписанию и правкой руками.
• Фаза 2. Веб-дашборд поверх той же базы (FastAPI): история находок, ручной запуск проверки. Добавляется, когда логика обнаружения проверена на реальных данных.

Уведомления будут реализованы через единый интерфейс Notifier — под него подключается отдельная реализация на каждый канал (Telegram, email и далее). Это позволяет добавлять новые каналы без изменений в остальном коде.

Для связи находок с конкретными проектами каждый репозиторий- потребитель API может завести у себя api_manifest.yaml со списком используемых эндпоинтов. api-crash-dog сверяет найденные изменения с манифестами и указывает, какие проекты потенциально затронуты.

Стек

Python 3.11+, SQLite, FastAPI (фаза 2). Разработка — Windows, PowerShell, .venv.

Контекст

Один из инструментов в наборе для интеграции с API российских маркетплейсов и сервисов — наряду с wb-barcode-gui, wb-api-workbench, wb-boss-widget.

Статус

Концепт, начальная разработка. MVP — площадки со структурированным диффом, начиная с Wildberries.