Переводите запросы чтения в документированный формат архива

Авторизация и сопоставление операций

Извлечение использует GET на https://api.redditproxy.com с X-API-Key: <key> либо Authorization: Bearer <key>. Оба варианта допустимы. Bearer — способ передачи ключа архива, а не совместимость с Reddit OAuth. Храните настоящий ключ в серверной конфигурации. Сессионная 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 выполняет текстовый поиск, а не произвольный язык запросов или анализ тональности. subreddit и author ограничивают совпадения. from и to задаются строго как YYYY-MM-DD в UTC и применяются к created_utc, не ко времени загрузки в архив. День to включается полностью. Не переносите старые временные метки или локальную часовую зону без проверки: интервалы внутри дня обрабатываются локально по доступным временным меткам записей. min_score задаёт числовой порог оценки, не меняя порядок. Внутренний порядок документов _doc не является порядком идентификаторов, загрузки, времени публикации, релевантности или оценки. limit и page принимают 1–100. Каждый запрос получает одну страницу максимум из 100 записей, а один набор фильтров допускает до 100 страниц. Разбиение обращений помогает организовать работу, но не гарантирует исчерпывающую выборку или отсутствие повторов. Успешный ответ содержит data, pagination и credits. Проверьте массив data и необходимые поля перед преобразованием; поля могут отсутствовать или различаться. parent_id и link_id не являются фильтрами запроса. Читайте pagination.total с pagination.relation: eq — точный итог запроса, gte — нижняя граница, unknown — отсутствие надёжного итога, возможно null. Даже точный итог не доказывает полную загрузку совпадений или наличие всех исторических записей.

Результаты HTTP и списание кредитов

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

Некорректные запросы не списывают кредиты, а сбои источника возвращают резерв. Успешное извлечение стоит один кредит, даже при пустом результате. Клиент может потерять ответ после оплаченного успеха сервера; успешный повтор стоит ещё один кредит. Отделяйте ошибку локального преобразования от HTTP-результата архива, чтобы отказ вашего адаптера или хранилища не превращался в предположение о возврате зарезервированного кредита.

Баланс, счета и перевыпуск ключа доступны в кабинете, не через публичный статус. До оплаты войдите и явно создайте счёт, затем переведите показанную точную сумму получателю из счёта и отправьте хеш транзакции на проверку. Счёт действует один час; срок зачисления не гарантируется. При сбое провайдера проверка может остаться в ожидании, что не является основанием повторно отправлять платёж.