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