Зафиксируйте контракт чтения до написания преобразователя

Маршруты и аутентификация Reddit Extract, пределы пагинации и локальная проверка типов, пропусков и ссылок в плоских архивных записях.

Получить API-ключ

Маршруты и два варианта передачи ключа

Базовый адрес API — https://api.redditextract.com. Маршрут /v1/search ищет посты и комментарии, /v1/posts ограничивает тип постами, а /v1/comments — комментариями. Для этих запросов id не требуется. /v1/item получает одну архивную запись по id; она может отсутствовать. /v1/subreddits предназначен для поиска сообществ по prefix и limit, а не для получения полного каталога или содержимого обсуждений.

Защищённые запросы принимают X-API-Key с исходным ключом либо Authorization: Bearer с тем же ключом. Это ключ аккаунта redditextract.com, а не токен Reddit OAuth. Авторизация на странице кабинета и сессионная cookie сайта не заменяют такой заголовок при чтении API. Баланс также относится только к этому домену. Не передавайте секрет в журнал преобразования, открытый репозиторий или клиентский JavaScript.

Для содержимого документированы q, subreddit, author, kind, from, to, min_score, limit и page. kind принимает post или comment. Даты from и to задаются как YYYY-MM-DD в UTC и фильтруют created_utc; день to включается целиком; limit и page находятся в диапазоне 1–100. У /v1/item используется id, у /v1/subreddits — prefix и limit. Не переносите все фильтры на любой маршрут: неизвестные параметры отклоняются, а выбора возвращаемых полей через fields нет.

Типы проверяет ваша схема назначения

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

Не преобразуйте идентификатор в число только ради удобства хранения. Проверьте рейтинг до числового преобразования, а представление и единицы времени — до работы с датой. Пропуск текста, пустая строка и null могут требовать разных решений. Сохраняйте исходное значение рядом с производным, если это нужно для диагностики. Наличие parent_id или link_id разрешает локальное сопоставление, но не гарантирует доступность соответствующей записи.

Важно отметить, что min_score является исключительно фильтром, а не параметром сортировки результатов. Выдача следует порядку _doc, который не означает хронологию, релевантность или убывание рейтинга. Не более 100 записей на запрос и 100 страниц на набор условий ограничивают сбор. Отношения eq, gte и unknown означают точный итог, нижнюю границу и отсутствие надёжного итога соответственно; они не доказывают полноту исторического архива.

Различайте HTTP-ошибку и ошибку своей обработки

Код 400 обозначает неверный запрос, 401 — отсутствующий или недействительный ключ, 402 — недостаток кредитов, 429 — ограничение частоты. Сначала исправляйте причину, а не повторяйте запрос без изменений. Если HTTP-ответ получен успешно, но ваш код не смог прочитать поле, сохраните этот ответ для разбора ошибки. Исключение в преобразователе не означает, что API-запрос не состоялся или должен быть бесплатным.

Один успешный запрос списывает один кредит, даже когда записей нет. Запрос, отклонённый до извлечения, не покупает данные; при ошибке вышестоящего источника зарезервированный кредит возвращается. Повторное чтение сохранённого файла API не вызывает. /v1/status является публичным и бесплатным: он сообщает статическое описание сервиса и ответ HTTP-сервера, но не проверяет ключ, баланс, поиск, наличие записей или полноту выдачи.

Маршруты API

Метод	Маршрут	Параметры
`GET`	`/v1/search`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/posts`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/comments`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/item`	`id`
`GET`	`/v1/subreddits`	`prefix, limit`
`GET`	`/v1/status`	`—`

Параметры запроса

Параметр	Значение / тип / диапазон
`q`	`text`
`subreddit`	`keyword`
`author`	`keyword`
`kind`	`post \| comment`
`from`	`ISO date`
`to`	`ISO date`
`min_score`	`integer`
`limit`	`1–100`
`page`	`1–100`
`id`	`item ID`
`prefix`	`subreddit prefix`