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