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