Документация API
Короткая инструкция по интеграции: как передавать API-ключ, выбрать структуру ответа, выполнить первый запрос, обработать ошибки и проверить тестовые данные.
Здесь собраны правила, которые не зависят от конкретного API-метода: авторизация, версия ответа, обработка ошибок, повторы запросов, тестовый API и проверки перед запуском.
Параметры, схемы и примеры конкретного API-метода смотрите в API-справочнике. Страницы платформ нужны для сравнения покрытия и групп методов.
Передавайте API-ключ в заголовке `X-API-Key` во всех запросах к Platform API.
Ключ не наследуется из сессии кабинета. Backend-сервисы, воркеры и фоновые задачи должны добавлять этот заголовок явно.
V1 и V2 открывают один каталог API-методов, но возвращают разные структуры данных. Выберите версию до разработки клиента и закрепите ее в конфигурации интеграции.
Не смешивайте V1 и V2 в одном потоке обработки. Это усложняет маппинг, кеширование, тесты и поддержку.
Сохраняет структуру ответа исходной платформы с минимальными преобразованиями со стороны Scrape Storm.
Миграции, обратная совместимость и клиенты, которые уже завязаны на поля исходной платформы.
Дает более стабильную модель данных для продуктового кода, аналитики и внутренних сервисов.
Новые интеграции, новые сервисы и любая логика, где не нужно сохранять исходную форму ответа платформы.
После выбора версии проверьте интеграцию на одном рабочем 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` на тестовый идентификатор из своего сценария.
Публичные platform API-методы и в V1, и в V2 используют один и тот же внешний envelope: `success`, `status` и `data`. Для списков сверху может добавляться `pagination`.
Выбор версии меняет схему внутри `data`, а не транспортную обертку. Точные поля конкретного API-метода смотрите в API-справочнике выбранной версии.
| Сценарий ответа | Верхний уровень | Что читать первым |
|---|---|---|
| Успешный ответ |
success,
status,
data
|
Полезная нагрузка метода лежит в `data`. |
| Успешный ответ со списком |
success,
status,
pagination,
data
|
`pagination` остается сверху, а данные метода все равно лежат в `data`. |
| Ответ с ошибкой |
success,
status,
error,
meta
|
Ветвление клиента делайте по HTTP status и `error.code`. |
Ошибки возвращаются в едином envelope. Клиентская логика должна опираться на HTTP status и `error.code`. Поле `message` подходит для отображения или логов, но не как условие в коде.
| HTTP status | 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
|
Примените backoff на уровне API-метода, а не останавливайте всю интеграцию, если остальные методы работают. |
| 500 |
Внутренняя ошибка сервера
INTERNAL_SERVER_ERROR
|
Повторите запрос с ограниченным backoff. После лимита попыток логируйте и передавайте ошибку в мониторинг. |
Тестовые API-методы возвращают статические JSON-примеры без обращения к исходным платформам. Используйте их для разработки клиента, интерфейса и тестов парсинга.
| Тестовый API | https://www.scrapestorm.net/api-mock |
|---|---|
| Пример | https://www.scrapestorm.net/api-mock/v2/youtube.com/profile/about-by-user-identifier |
| API-справочник |
Проверьте эти пункты перед рабочим трафиком и перед увеличением параллельных воркеров.
Новые клиенты используют V2. V1 разрешен только для совместимости или миграции существующей интеграции.
Ключ находится в secret storage и не попадает во фронтенд, публичные репозитории, клиентские бандлы и логи.
Ветки клиента строятся на HTTP status и `error.code`. Поле `message` не участвует в логике.
`RATE_LIMIT_EXCEEDED` ждет `Retry-After` или `error.retry_after_seconds`. `402` и `422` не повторяются без изменения причины. `500` и `503` имеют backoff и лимит попыток.
Очередь или rate limiter ограничивает одновременные запросы от воркеров, cron-задач и фоновых процессов.
Тестовый API используется для формы ответа. Рабочий API подтверждает реальные параметры, лимиты, доступность метода и списание кредитов.
Перед ростом трафика проверьте стоимость используемых API-методов.
Откройте API-справочник нужной версии для параметров, схем и примеров конкретного API-метода. Для выбора платформы и группы методов используйте раздел Платформы.