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