Аутентификация и результаты запросов
Отправляйте GET-запросы к https://api.subredditapi.com, передавая X-API-Key: <ключ> или Authorization: Bearer <ключ>. Поддерживаются оба заголовка. Храните секрет в конфигурации серверного клиента, а не в общедоступном наборе данных или журнале запросов. Кабинет использует отдельный Secure HttpOnly cookie для сессии. Вход в кабинет не заменяет заголовок с ключом, необходимый для получения архивных записей исследовательским приложением.
HTTP 400 означает некорректный запрос, 401 — отсутствующий или недействительный ключ, 402 — нехватку кредитов, 429 — ограничение частоты. После 400 исправляйте параметры, после 401 проверяйте учетные данные, после 402 приостанавливайте сбор или решайте вопрос пополнения. Для 429 предусмотрите ожидание и предел повторов. Проверяйте статус ответа до разбора его содержимого как успешной страницы, чтобы сообщение об ошибке не попало в исследовательскую таблицу.
Успешный запрос расходует один кредит, даже если совпадений нет. Некорректные запросы не списывают баланс, а сбой вышестоящего сервиса возвращает зарезервированный кредит. Ошибка соединения клиента может возникнуть после успешного платного получения данных сервером; другой успешный запрос оплачивается отдельно. Различайте в журнале попытки, фактически полученные страницы и записи, принятые в выборку. Локальное отклонение нерелевантного текста не отменяет стоимость успешного обращения к API.
Маршруты и точные фильтры
Доступны /v1/search, /v1/posts, /v1/comments, /v1/item, /v1/subreddits и /v1/status. Поиск применяет поддерживаемые текстовые условия, а маршруты публикаций и комментариев выбирают соответствующий тип записей. Только /v1/item требует id известного элемента; id не является фильтром публикаций и комментариев. Для знакомства с названиями сообществ используйте /v1/subreddits с prefix и limit, не считая агрегированные количества глобально точными.
Параметры поиска: q, subreddit, author, kind, from, to, min_score, limit и page. kind принимает post либо comment. Даты задаются в формате YYYY-MM-DD в UTC, причем день to включается в интервал. min_score отсекает записи ниже числового порога, но не сортирует. Произвольная программа запросов, серверная оценка тональности и пользовательская аналитика не предоставляются; анализ полученного текста выполняется на стороне клиента.
При использовании маршрутов /v1/posts и /v1/comments не требуется указывать идентификатор элемента, так как эти эндпоинты предназначены для листинга и фильтрации множества записей. Идентификатор требуется только для маршрута /v1/item, который возвращает конкретную запись. Ответы API представляют собой плоские записи, а не серверные деревья обсуждений, что требует локальной группировки данных на стороне клиента при необходимости восстановления контекста цепочек комментариев. Поля parent_id и link_id используются для такого связывания только при их наличии; они не являются доступными фильтрами, а вся цепочка родительских записей не гарантируется.
В примере soil выбирает поисковый текст, gardening — одно сообщество, limit=3 — максимум три записи. Для сравнения со второй группой выполните отдельный запрос и сохраните остальные условия. Нельзя передать несколько названий как установленный многозначный фильтр subreddit. Одинаковая конфигурация делает правила отбора понятными, но не выравнивает покрытие архива и не превращает полученные фрагменты в перепись участников сообщества.
Пагинация и интерпретация счетчиков
Значения limit и page находятся в диапазоне от 1 до 100. Один запрос получает одну страницу максимум из 100 записей, а не сто страниц одновременно. Внутренний порядок документов _doc не соответствует хронологии, релевантности или рейтингу. Локальная сортировка показывает последовательность только среди полученных объектов. Исчерпание всех разрешенных страниц не гарантирует полного списка совпадений или отсутствия повторяющихся записей между сохраненными частями выборки.
Итог нужно читать вместе с relation: eq означает точное число совпадений запроса, gte — нижнюю границу, unknown — отсутствие надежного итога, который может быть null. Нижняя граница не является точным количеством. Даже точный счетчик не доказывает, что клиент получил все материалы. Разделение запросов по датам помогает организовать работу, но не подтверждает полноту покрытия или отсутствие пересечений между наборами.
Сохраняйте реальные ответы, параметры, время получения и версию локальной обработки. Это помогает объяснять состав выборки и повторять анализ уже загруженных файлов. Удаленный повтор не обещает тех же записей. Публичный /v1/status не требует ключа и не тарифицируется; он возвращает статическое описание исторического сервиса и ответ HTTP-приложения. Поиск, доступность конкретного материала, нагрузку и скорость получения записей этот маршрут не проверяет.
