Документация API
Короткая инструкция по интеграции: как передавать API-ключ, выбрать структуру ответа, выполнить первый запрос, обработать ошибки и проверить тестовые данные.
Здесь собраны правила, которые не зависят от конкретного API-метода: авторизация, версия ответа, обработка ошибок, повторы запросов, тестовый API и проверки перед запуском.
Параметры, схемы и примеры конкретного API-метода смотрите в API-справочнике. Страницы платформ нужны для сравнения покрытия и групп методов.
Передавайте API-ключ в заголовке `X-API-Key` во всех запросах к Platform API.
Ключ не наследуется из сессии кабинета. Backend-сервисы, воркеры и фоновые задачи должны добавлять этот заголовок явно.
V1 и V2 открывают один каталог API-методов, но возвращают разные структуры данных. Выберите версию до разработки клиента и закрепите ее в конфигурации интеграции.
Не смешивайте V1 и V2 в одном потоке обработки. Это усложняет маппинг, кеширование, тесты и поддержку.
Сохраняет структуру ответа исходной платформы с минимальными преобразованиями со стороны ScrapeStorm.
Миграции, обратная совместимость и клиенты, которые уже завязаны на поля исходной платформы.
Дает более стабильную модель данных для продуктового кода, аналитики и внутренних сервисов.
Новые интеграции, новые сервисы и любая логика, где не нужно сохранять исходную форму ответа платформы.
После выбора версии проверьте интеграцию на одном рабочем API-методе: базовый URL, заголовки, query-параметры, таймаут и обработку ошибки.
| HTTP-метод | GET |
|---|---|
| Эндпоинт | /api/v2/youtube.com/profile/about-by-user-identifier |
| Пример query-параметра | user_identifier=mkbhd |
| Заголовок | X-API-Key |
В примере используется YouTube API-метод `profile/about-by-user-identifier`. Замените `user_identifier` на тестовый идентификатор из своего сценария.
Публичные методы API платформ в V1 и V2 используют общую внешнюю структуру ответа: `success`, `status` и `data`. Для списков на верхнем уровне может добавляться `pagination`.
Выбор версии меняет схему внутри `data`, а не транспортную обертку. Точные поля конкретного API-метода смотрите в API-справочнике выбранной версии.
| Сценарий ответа | Верхний уровень | Что читать первым |
|---|---|---|
| Успешный ответ |
success,
status,
data
|
Полезная нагрузка метода лежит в `data`. |
| Успешный ответ со списком |
success,
status,
pagination,
data
|
`pagination` остается сверху, а данные метода все равно лежат в `data`. |
| Ответ с ошибкой |
success,
status,
error,
meta
|
Разделяйте сценарии обработки по коду состояния HTTP и `error.code`. |
Ошибки возвращаются в единой структуре ответа. Клиентская логика должна опираться на код состояния HTTP и `error.code`. Поле `message` подходит для отображения и журналирования, но не для управления логикой приложения.
| Код состояния HTTP | Error code | Действие клиента |
|---|---|---|
| 401 |
Неавторизованный запрос
UNAUTHORIZED
|
Проверьте API-ключ и окружение. Не повторяйте запрос в цикле с тем же ключом. |
| 422 |
Ошибка валидации
VALIDATION_FAILED
|
Исправьте параметры запроса. Тот же ввод вернет ту же ошибку. |
| 402 |
Недостаточно кредитов
INSUFFICIENT_CREDITS
|
Остановите сценарий до пополнения баланса или изменения лимитов аккаунта. |
| 429 |
Превышен лимит параллельных соединений
CONCURRENT_CONNECTIONS_EXCEEDED
|
Снизьте параллелизм на один API-ключ или поставьте запросы в очередь. |
| 429 |
Превышен рейт-лимит
RATE_LIMIT_EXCEEDED
|
Дождитесь опубликованного retry-интервала и синхронизируйте повторы между воркерами. |
| 503 |
API-метод временно недоступен
ENDPOINT_UNAVAILABLE
|
Увеличивайте задержку повторных запросов к этому API-методу. Остальные работающие методы можно продолжать использовать. |
| 500 |
Внутренняя ошибка сервера
INTERNAL_SERVER_ERROR
|
Повторите запрос с увеличивающейся задержкой и ограничением числа попыток. Если попытки исчерпаны, запишите ошибку в журнал и передайте её в мониторинг. |
Тестовые API-методы возвращают статические JSON-примеры без обращения к исходным платформам. Используйте их для разработки клиента, интерфейса и тестов парсинга.
| Тестовый API | https://www.scrapestorm.net/api-mock |
|---|---|
| Пример | https://www.scrapestorm.net/api-mock/v2/youtube.com/profile/about-by-user-identifier?user_identifier=mkbhd |
| API-справочник |
Проверьте эти пункты перед рабочим трафиком и перед увеличением параллельных воркеров.
Новые клиенты используют V2. V1 разрешен только для совместимости или миграции существующей интеграции.
Ключ находится в secret storage и не попадает во фронтенд, публичные репозитории, клиентские бандлы и логи.
Сценарии обработки строятся на коде состояния HTTP и `error.code`. Поле `message` не участвует в логике.
После `RATE_LIMIT_EXCEEDED` ждите время, указанное в `Retry-After` или `error.retry_after_seconds`. Запросы с ответами `402` и `422` повторяйте только после устранения причины. После `500` и `503` увеличивайте задержку и ограничивайте число попыток.
Очередь или rate limiter ограничивает одновременные запросы от воркеров, cron-задач и фоновых процессов.
Тестовый API используется для формы ответа. Рабочий API подтверждает реальные параметры, лимиты, доступность метода и списание кредитов.
Перед ростом трафика проверьте стоимость используемых API-методов.
Откройте API-справочник нужной версии для параметров, схем и примеров конкретного API-метода. Для выбора платформы и группы методов используйте раздел Платформы.