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