Первый запрос
Отправляйте запрос с сервера и храните API-ключ в секрете.
: "${REDDITAPP_API_KEY:?Set REDDITAPP_API_KEY on your server}"
curl --get --fail-with-body 'https://api.redditapp.com/v1/search' \
-H "Authorization: Bearer ${REDDITAPP_API_KEY}" \
--data-urlencode 'q=offline maps' \
--data-urlencode 'subreddit=hiking' \
--data-urlencode 'limit=3'Справочник API
↔ Прокрутите таблицу по горизонтали
Маршруты 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 | — |
Дополнительные замечания
GET | /v1/search · /v1/posts · /v1/comments · /v1/item · /v1/subreddits · /v1/status |
|---|---|
q · subreddit · author · kind | kind: post | comment |
from · to | YYYY-MM-DD |
min_score | score ≥ min_score |
limit · page | 1…100 · 1…100 |
/v1/item | id |
/v1/subreddits | prefix · limit |
_doc | ≠ date · ≠ relevance · ≠ score |
pagination.relation | eq · gte · unknown |
pagination | has_more · window_exhausted · truncated |
1 credit | $0.001 |
$1 | 1000 credits |
$50 | 50000 credits |
400 · 401 · 402 · 429 · 502 | HTTP |
Поместите свой бэкенд между приложением и архивом
В иллюстративном туристическом приложении мобильный или веб-клиент отправляет фразу offline maps вашему бэкенду. Бэкенд проверяет запрос, применяет ограничения приложения и обращается к архиву с сохранённым ключом сервиса. Возвращайте только поля, нужные экрану чтения. Пример — отправная точка проектирования, а не утверждение, что этот аккаунт уже получил записи о походах.
Используйте GET https://api.redditapp.com/v1/search?q=offline%20maps&subreddit=hiking&limit=3&page=1. Передавайте с бэкенда заголовок X-API-Key: YOUR_SAVED_KEY либо Authorization: Bearer YOUR_SAVED_KEY. Не помещайте учётные данные в URL, клиентские сборки или публичные журналы. Сессионная cookie страницы аккаунта не заменяет аутентификацию запросов данных.
Выбирайте фильтры, которые сервис действительно принимает
Поиск принимает q, subreddit, author, kind, from, to, min_score, limit и page. q использует сопоставление AND по title и text; это не обещание поиска точной фразы или семантического совпадения. kind принимает post или comment. Subreddit и author — точные фильтры полей. min_score отбирает записи, но не сортирует их.
Задавайте from и to датами YYYY-MM-DD в UTC. Дата to включает весь соответствующий день UTC. Например, from=2025-01-01 и to=2025-12-31 определяют диапазон дат, не запрашивая сортировку по времени. Не передавайте строки ISO с датой и временем, произвольный DSL запросов, параметр sort или фильтры parent_id/link_id. Неподдерживаемые параметры отклоняются.
Выберите эндпоинт под задачу
GET /v1/posts и GET /v1/comments ограничивают вид записи и принимают поисковые фильтры; id им не требуется. GET /v1/item?id=RECORD_ID ищет доступную запись по её идентификатору. GET /v1/subreddits?prefix=hik&limit=3 возвращает ограниченную агрегацию сабреддитов; её счётчики не гарантируют глобально точных значений.
GET /v1/status открыт без ключа и не тарифицируется. Он возвращает статическое пояснение об историческом архиве и показывает, что HTTP-обработчик отвечает. Он не обращается к поисковому бэкенду, не устанавливает охват содержимого и не измеряет работоспособность архива. Ни один из этих эндпоинтов не предоставляет публикацию, голосование, сообщения, закладки аккаунта или полное дерево беседы.
Разберитесь в полях пагинации перед добавлением «Показать ещё»
Ответы на запросы данных содержат data, pagination и credits. Записи в data — плоские объекты исходного источника; выбранные title, author, дата или permalink могут отсутствовать. Архив использует порядок _doc, а не хронологическую сортировку, релевантность или оценку. Локальная сортировка меняет порядок загруженного подмножества, но не делает его глобально самым новым или высокооценённым.
Увеличивая pagination.page, сохраняйте те же фильтры и limit. pagination.has_more использует дополнительную запись для проверки продолжения, когда она доступна. Если значение false, не предлагайте автоматический следующий запрос. pagination.window_exhausted обозначает последнюю страницу ограниченного окна; достижение этой границы не доказывает, что получен весь подходящий материал архива.
Допускаются 1–100 записей и страницы 1–100. Читайте pagination.total вместе с pagination.relation: eq означает точное значение в рамках правил подсчёта ответа, gte — нижнюю границу, unknown — отсутствие надёжного общего количества, которое может быть null. Пустая страница после первой не доказывает общий итог. На полной странице 100 при limit=100 нет места для дополнительной проверочной записи, поэтому итог — нижняя граница; на границе страниц has_more равен false. Для агрегации сабреддитов общее количество неизвестно, а pagination.truncated отмечает пропущенные группы агрегации.
Явно обрабатывайте оплату и неудачные запросы
Успешный запрос данных стоит один кредит, в том числе при пустом массиве data. Проверяйте ввод до отправки и не загружайте страницы только ради анимации индикатора. HTTP 400 означает неверный ввод; 401 — отсутствующий или недействительный ключ сервиса; 402 — недостаток кредитов; 429 — ограничение частоты. Такие отклонённые запросы не резервируют кредит на получение данных.
Неудачный запрос к вышестоящему сервису возвращает HTTP 502 и освобождает зарезервированный кредит либо сообщает об ожидающей сверке возврата. Если ответ потерян на границе вашего приложения, исход остаётся неизвестным; не считайте запрос бесплатным. Сохраняйте состояние поиска, соблюдайте Retry-After и при необходимости давайте пользователю самому выбрать повтор. Работа с ключами и балансом принадлежит оператору, а не туристу.
Превратите ответ в честный экран чтения
Экранируйте текст записей перед выводом. Сохраняйте идентичность источника и ссылку, если она есть, обозначайте отсутствующую дату как неизвестную и различайте время создания записи и время её получения приложением. Идентификаторы родителя и обсуждения могут поддержать локальную группировку, если присутствуют, но не восполняют отсутствующих предков.
В разделе «Состояния интерфейса» разбираются предлагаемые сообщения загрузки, пустого ответа и ошибки. «Практические заметки» на странице «Сценарий приложения» посвящены карточкам, локальным ссылкам и бюджету запросов. Раздел «Ключ и кредиты» объединяет создание аккаунта и цены. Проверяйте и тестируйте собственную реализацию; примеры не доказывают её работоспособность и не являются актуальными советами для похода.
