Быстрый старт с единым API данных: от каталога возможностей к первому полученному результату

Написать код запросов для одной платформы обычно несложно. Настоящие трудности начинаются со второй платформой: меняются имена параметров, различаются идентификаторы пользователей и контента, одни эндпоинты сразу возвращают данные, а другие сначала создают задачи. Когда начинают работать cron-задачи, у повторных попыток, дедупликации и сверки оплаты появляются собственные отдельные ветки кода.

Единый API данных избавляет от этих лишних затрат на интеграцию. В EveryData от EveryInfra везде используется одна и та же Bearer-аутентификация: платформа выбирается через platform, возможность через action, а параметры конкретной возможности передаются в params. Унифицированы точка входа для вызова и общий порядок обработки, но данные всех платформ не приводятся принудительно к одному бизнес-объекту.

В этом руководстве показан минимальный запрос на примере поиска заметок в Xiaohongshu, а затем объясняется, как перейти к другим возможностям. Цель не ограничивается одним HTTP-запросом: программа должна знать, какие данные она получила, какие результаты ещё ожидаются и как следующий запуск восполнит пробел. Примеры основаны на публичных каталогах и реализации, проверенных по состоянию на 2026-09-04. Фрагменты POST-запросов для продакшена служат шаблонами вызова для разрешённых сценариев, а не результатами новых успешных замеров в рабочей среде.

Сначала определите, что вам нужно: получение данных или поиск и генерация

Если вы уже знаете, к какой платформе относится цель, например конкретная заметка, товар или место, и хотите прочитать её структурированные поля, начинайте с API данных. Если вы ещё выясняете, где в сети есть нужные материалы, сначала выполните веб-поиск. Если материалы уже есть и их нужно резюмировать, классифицировать или оформить в отчёт, используйте обработку моделью.

Возьмём анализ комментариев. Сбор данных отвечает на вопрос, что это за комментарии и откуда они, а модель отвечает на вопрос, какие проблемы встречаются в этих текстах. Модель не может придумать записи, пропущенные из-за ошибок сбора, или считать невозвращённое число комментариев нулём. Если разделить эти два этапа, при спорных выводах можно вернуться к исходным доказательствам, а не заново выстраивать всю цепочку вызовов на основе догадок.

Шаг 1. Проверяйте возможности по каталогу, а не угадывайте эндпоинты по названиям платформ

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

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?compact=1' \
  | jq '.capabilities[] | {platform, action, required_params, mode, available}'

Например, чтобы найти заметки Xiaohongshu по ключевому слову для исследования, сначала смотрите search. Если у вас уже есть ссылка на заметку и нужны её детали или комментарии, выберите note или comments соответственно. Похожие названия не означают взаимозаменяемости: ключевое слово для поиска нельзя передать вместо URL в запросе деталей.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=xiaohongshu' \
  | jq -e '.capabilities[] | select(.action == "search") | {
      platform, action, required_params, optional_params,
      param_meanings, mode, returns_list,
      default_limit, max_limit, response_fields, available
    }'

В этой проверке каталога для xiaohongshu.search обязательным параметром был keyword, mode имел значение sync, а returns_list значение true; количество по умолчанию 20, верхний предел 50. Последние два значения описывают настройки количества для этой возможности, а не гарантию выдачи в каждом запросе и не общий лимит для всех платформ. В каталоге также указаны sort и content_type. Для фильтрации используйте допустимые значения из param_meanings и не копируйте перечисления с другой платформы.

• required_params: обязательные входные параметры. Сначала заполните их, а затем постепенно добавляйте фильтры.
• param_meanings: описания параметров и объявленные допустимые значения. Не придумывайте собственные перечисления для полей, которых нет в списке.
• mode и returns_list: определяют, нужен ли опрос задачи и будут ли итоговые бизнес-данные списком или одним объектом.
• response_fields: используется для планирования сопоставления полей. Это не реальный ответ и не гарантия того, что у каждого поля будет непустое значение.
• available: флаг доступности на уровне каталога. Он не доказывает заранее, что целевой URL вернёт данные прямо сейчас.

Возможности, возвращающие списки, также поддерживают общие параметры ограничения количества, которые могут не повторяться в optional_params. Это различие проверяется кодом валидации запросов. При интеграции изучайте вместе объявления списков, значения по умолчанию и пределы, а также полные описания. Не удаляйте допустимые параметры ограничения только потому, что строковое сравнение не нашло их в optional_params.

Шаг 2. Отправьте запрос, достаточно небольшой, чтобы его было легко проверить

Подготовьте API-ключ с нужными правами на возможности и передавайте его через переменные окружения сервера. Не размещайте его в коде фронтенда, на скриншотах или в публичных файлах с примерами. В примерах ниже предполагается, что EVERYINFRA_API_KEY задан через ваше собственное хранилище секретов. Команды отправляют один запрос без автоматических повторных попыток.

: "${EVERYINFRA_API_KEY:?set the server-side API Key first}"
curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{
    "platform": "xiaohongshu",
    "action": "search",
    "params": {
      "keyword": "AI tools",
      "limit": 5
    }
  }'

Число 5 здесь обозначает желаемый размер небольшой выборки, а не гарантию выдачи; 180 секунд означает тайм-аут ожидания клиента в этом примере, а не SLA сервиса. Прежде чем увеличивать объём, проверьте поля, формат временных меток и ссылки на источники на небольшом наборе результатов. При первичной отладке сохраняйте строку HTTP-статуса и тело ответа, чтобы при кодах 4xx или 5xx видеть конкретную ошибку, а не общее сообщение о сбое curl.

Три поля верхнего уровня нужно держать раздельно: platform и action выбирают возможность, а все бизнес-условия передаются в params. Не выносите keyword на верхний уровень и не добавляйте page, cursor или sort к действиям, которые их не поддерживают. Параметры, которых нет в каталоге, нельзя считать поддерживаемыми только потому, что так устроено большинство API.

OpenAPI помогает людям и программам описывать тела запросов, параметры и ответы, но не требует одинаковых бизнес-моделей на всех платформах. При генерации типов или написании клиентов используйте спецификацию, чтобы понять формат описания интерфейсов, а конкретные поля определяйте по каталогу и формату ответа самого сервиса.

Шаг 3. Разберитесь во внешней и внутренней структуре синхронных результатов

Для выбранного действия xiaohongshu.search реализация помещает списки в results, а рядом с ними возвращает внешние метаданные: id, platform, action, count, billing и quota. Внешний id — это идентификатор отслеживания запроса, а id каждой записи внутри results — идентификатор контента. Не путайте их: первый нужен для отладки и сверки, второй — для дедупликации записей.

Не считайте results единственным путём к данным для любого клиента. Другие действия могут возвращать бизнес-объекты под другими именами. returns_list указывает форму объекта, а словари полей описывают внутренние поля, но ни то ни другое не заменяет проверки внешней структуры выбранной возможности. Для каждой новой возможности нужна явная конфигурация адаптации результата, а не рекурсивный поиск первого массива в любом ответе.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/fields?platform=xiaohongshu&action=search' \
  | jq '{fields, undocumented}'

На выводы часто влияют две особенности обработки полей. Во-первых, null в метриках вовлечённости означает, что данные не опубликованы или недоступны; перед расчётом средних не подставляйте вместо таких значений 0 автоматически. Во-вторых, публичная документация допускает сохранение в posted_at исходных строк временных меток платформы, поэтому не рассчитывайте, что все значения можно напрямую разобрать в едином формате ISO. Храните разобранные временные метки отдельно и сохраняйте флаг, отмечающий ошибку разбора. При ошибке не подставляйте текущую дату.

Если в ответе есть флаги partial или missed, цели, по которым данные не получены, нужно учитывать отдельно: HTTP 200 не гарантирует получение данных по каждой цели в пакете. Из пустого массива можно сделать только один вывод: в этот раз записи не были возвращены. Это не означает, что данных нет на исходной платформе. Отдельно проверьте, охватили ли запросы нужные объекты и соблюдены ли заданные ограничения охвата.

Шаг 4. Для асинхронных возможностей дожидайтесь конечного состояния задачи, не останавливайтесь на job_id

При переходе к возможностям с mode, равным async, ответ на отправку может содержать HTTP 202, status, job_id и poll_url. Сохраните эти поля, прежде чем запрашивать статус задачи. Согласно спецификации HTTP, код 202 означает, что запрос принят, но обработка ещё не завершена; не используйте его для запуска бизнес-уведомлений вроде «отчёт сформирован».

: "${EVERYINFRA_API_KEY:?set the API Key used for this task first: API Key}"
: "${EVERYINFRA_JOB_ID:?paste the job_id from the actual submit response}"
curl --silent --show-error --include --max-time 30 \
  "https://api.everyinfra.com/api/v1/jobs/${EVERYINFRA_JOB_ID}" \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}"

В текущих реализациях задачи ищутся по API-ключу, использованному при отправке. Запрашивайте задачу с тем же API-ключом и не рассчитывайте, что другой ключ того же аккаунта позволит её получить. Если задача не найдена, не создавайте сразу такую же заново. Проверьте домены API, значения job_ids и использованные API-ключи; при необходимости сверяйтесь с сохранёнными данными запроса.

• running или finalizing: задача обрабатывается. Сохраните задачу и продолжайте опрос с ограниченными интервалами.
• succeeded: задача успешно завершена; разберите объект данных возможности и проверьте выполнение бизнес-требований.
• failed: задача завершилась с ошибкой; прочитайте error и сохраните записи о задаче, не считая это успехом с пустыми данными.
• Тайм-аут запроса статуса или неизвестный статус: только пометьте результат как неподтверждённый. Задайте общий лимит ожидания для последующего восстановления, не меняя статус на успех или ошибку.

Код опроса должен задавать максимальное время ожидания и постепенно увеличивать интервалы между запросами, чтобы избежать цикла без пауз. После перезапуска программы возобновляйте опрос по сохранённым job_ids, а не отправляйте задачи заново. Данные о списании при отправке сохраняйте отдельно: текущие ответы на запрос результата не повторяют блок billing целиком, поэтому отсутствие billing в результатах запроса не означает, что списаний не было.

Шаблон Asynchronous Request-Reply от Microsoft тоже разделяет приём запроса, проверку статуса и итоговый результат и описывает подсказки для опроса. Он полезен как ориентир при проектировании клиента, но заголовки вроде Location и Retry-After EveryInfra здесь не гарантирует: запросы статуса по-прежнему идут на точку входа, указанную в текущем ответе.

Шаг 5. Обрабатывайте ошибки по их причине и не повторяйте POST вслепую

При бизнес-ошибках проверяйте одновременно HTTP-статус и error.code. Текущие точки входа для данных сначала проверяют аутентификацию, затем возможность, права и параметры и только потом переходят к квотам и выполнению. Ответ 401 при отсутствии действующего API-ключа не подтверждает, что бизнес-параметры прошли валидацию.

• 401: проверьте наличие и действительность API-ключа, а также правильность заголовков аутентификации со схемой Bearer. Не пытайтесь исправить ошибку аутентификации, изменяя ключевые слова.
• 403: проверьте, есть ли у API-ключа доступ к нужным продуктам и возможностям. Вопросы прав должны решать уполномоченные сотрудники, без автоматического переключения аккаунтов.
• 400 unknown_capability: проверьте соответствие platform и action; заново прочитайте каталог и посмотрите варианты имён, предложенные сервисом.
• 422: проверьте обязательные параметры, неизвестные параметры и недопустимые значения перечислений. Устраняйте ошибки по одной, следуя подсказкам, и только потом отправляйте новые запросы.
• 402: недостаточно квоты; нужно решить вопрос с кредитами аккаунта, повтор тех же запросов ничего не изменит.
• 429, временные ошибки сервиса или обрывы сети: увеличивайте интервалы между попытками и выясняйте состояние исходного запроса. Повторяйте попытку не более заданного числа раз и только после проверки безопасности повтора.

Проще всего упустить случай, когда на стороне клиента произошёл тайм-аут, а сервер уже принял запрос. С точки зрения бизнеса сбор данных выглядит операцией только для чтения, но выполняется через POST и может создавать задачи и приводить к списаниям. Идентификаторы корреляции помогают связать несколько попыток, но сами по себе не гарантируют идемпотентность на стороне сервера. Не добавляйте заголовок Idempotency-Key без явной поддержки API и не рассчитывайте, что дублирующиеся запросы будут выполнены только один раз.

RFC 9110 строго ограничивает автоматические повторы неидемпотентных запросов. При таком неизвестном исходе сначала запросите существующие задачи или проверьте записи о запросах; если данных недостаточно, безопаснее оставить статус неизвестным, чем автоматически отправить весь пакет заново.

Шаг 6. Храните данные, статус сбора и списания отдельно

Главная польза единой точки входа в том, что она проясняет разделение между общими записями и сопоставлением полей конкретной платформы. Ведите как минимум три типа записей: бизнес-задачу, попытку вызова API и объект платформы. Так видно, сколько попыток прошла задача, а один и тот же контент из нескольких сборов обновляется без создания дублей.

• Записи задач: ваш task_id, охват целевых объектов, ожидаемые поля и критерии завершения. Завершение здесь определяется бизнес-критериями, а не только успешным HTTP-ответом.
• Записи запросов: platform, action, сводка нечувствительных параметров, время начала и окончания, ID запросов API, job_ids, статус и billing. Сохраняйте и неудачные попытки.
• Записи объектов: platform, тип объекта, id объекта, ссылки на источник, фактически полученные поля и observed_at; не объединяйте объекты разных платформ, у которых случайно совпали ID.

Это рекомендации для модели данных вашего приложения, а не дополнительные поля, которые возвращает EveryInfra. Сборщик должен записывать в observed_at время наблюдения, а posted_at указывает время публикации исходного контента. Вместе эти поля показывают, когда контент был опубликован и когда вы о нём узнали, что позволяет анализировать задержки данных и повторные наблюдения.

При сравнении платформ сопоставляйте только нужные бизнесу поля с сопоставимым смыслом. Лайки, добавления в избранное, рейтинги товаров и число комментариев относятся к разным метрикам; если переименовать их все в score, общей шкалы у них не появится. Для полей без описания сохраняйте состояние «отсутствует» или сверяйтесь со словарями, а не угадывайте единицы и смысл.

Списание нельзя восстановить по числу записей в результате. Возможности с несколькими целями тарифицируются за каждую цель, поэтому HTTP-запрос не является единицей оплаты, а небольшой лимит выборки не даёт пропорциональной скидки по числу возвращённых записей. Текущая синхронная реализация обрабатывает сценарии возврата средств при пустых результатах и частичной доставке, но клиент должен сохранять фактические данные billing и записи журнала операций для аудита; не считайте расчёты завершёнными только по ответу 200 или пустому массиву.

При логировании запросов ориентируйтесь на подход OWASP к идентификаторам взаимодействия: связывайте события в рамках одного бизнес-намерения и исключайте чувствительные данные, например токены доступа. Сохранять информацию для отладки не значит сбрасывать в логи заголовки запросов и исходный текст.

Какой код стоит переиспользовать при подключении второй платформы

Переиспользовать можно добавление данных аутентификации, настройки тайм-аутов, логирование ошибок, планировщики запросов статуса задач и журналирование событий безопасности. Имена и смысл параметров, пути к объектам результата, сопоставления полей, правила пагинации и критерии завершения должны оставаться привязанными к конкретной возможности. Разделение этих частей не позволит добавлению новых возможностей превратиться в копирование целых наборов клиентского кода.

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

С пагинацией и инкрементальной выгрузкой нужна особая осторожность. Используйте их, только если конкретное действие явно предоставляет параметры пагинации и признаки окончания; без них не формируйте курсоры на стороне клиента. Запросы по cron дают несколько наблюдений и не означают автоматически полную историю или весь новый контент. В первой версии отчёта явно укажите проверенные цели и временные окна, а не заявляйте о полном охвате, который нельзя доказать.

Для каких задач этот подход напрямую не подходит

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

Даже если данные видны публично, их хранение, анализ и повторный показ нужно оценивать с учётом правил конкретной платформы и бизнес-целей. Ограничивайте исследование необходимыми целями и полями, контролируйте сроки хранения и не выводите профили авторов, ссылки с параметрами доступа или исходный текст напрямую в публичные логи. Техническая возможность выполнить запрос и право использовать данные в бизнесе проверяются отдельно.

Начните с одного результата, который можно объяснить

Завершив первичную интеграцию, задайте себе четыре вопроса. Могу ли я точно назвать вызванную возможность? Могу ли я проследить каждую запись до источника? Различаю ли я успех, обработку, частичную доставку и неизвестный исход? Если запросы завершились ошибкой или продублировались, могу ли я объяснить получившиеся записи и списания?

Когда на все четыре вопроса есть ответы, подключайте новые платформы, увеличивайте число параллельных запросов и добавляйте анализ с помощью моделей. Ценность единых API данных не в том, что все различия исчезают, а в том, что собственную логику приходится писать только там, где платформы действительно различаются. Выберите возможность в документации ниже, проверьте небольшие выборки, правильно сохраните результаты и переходите к следующему шагу.