Вступ до інтеграції та підготовка
Почніть інтеграцію з реєстрації на сторінці отримання API-ключа. Він показується один раз відразу після створення облікового запису й до оплати. Зберігайте його окремо від коду, який отримують браузери відвідувачів. За наявності пробного балансу використайте його для першого запиту; можливі 100 пробних кредитів залежать від спільних для мережі обмежень проти зловживань, а не гарантуються кожному користувачеві.
Сервіс є незалежним історичним архівом, а не офіційним API Reddit або джерелом оновлень у реальному часі. Отримані записи описують збережені матеріали та можуть не відповідати поточному стану вихідної сторінки. Інтерфейс не призначений для голосування, публікації повідомлень чи приватного листування. Перш ніж будувати застосунок, визначте, яке запитання можна дослідити за обмеженою вибіркою історичних дописів і коментарів.
Плануйте бюджет за успішними запитами, а не за кількістю окремих записів. Кожен такий запит списує один кредит навіть за відсутності збігів; $1 оплачує 1000 успішних запитів. Мінімальне платне поповнення $50 додає 50000 кредитів. Один запит може повернути максимум 100 записів. Ці одиниці обліку допомагають порівняти заплановану кількість звернень із балансом, не припускаючи, що порожня відповідь нічого не коштує.
Автентифікація та основні кінцеві точки
У Python налаштуйте HTTP-клієнт, а в серверному JavaScript — виклик fetch, щоб передавати ключ у заголовку X-API-Key. Для отримання даних використовуйте GET-запити до /v1/search, /v1/posts або /v1/comments. Зберігайте налаштування автентифікації окремо від параметрів пошуку, щоб заміна ключа не вимагала переписування фільтрів. Якщо сервер повертає HTTP 401, перевірте наявність і чинність ключа замість сліпого повторення запиту.
Для фільтрації використовуйте q, subreddit, author, kind і дати from та to у форматі YYYY-MM-DD в UTC. min_score відсіює записи за мінімальною числовою оцінкою та не сортує їх. Порядок _doc не є хронологічним, релевантним чи впорядкованим за рейтингом. Зберігайте параметри поруч із локальною вибіркою, щоб під час аналізу було зрозуміло, які саме умови відбору застосовувалися.
Коли відомий ідентифікатор конкретного допису або коментаря, використовуйте /v1/item з параметром id. Для маршрутів /v1/posts та /v1/comments такий фільтр не передбачений. Відповідь містить плоскі записи. За наявності parent_id або link_id можна виконати локальне групування, проте це не гарантує повного дерева чи всіх попередніх повідомлень. У відображенні обговорення залишайте можливість позначити відсутній контекст замість його вигадування.
Обробка помилок, лімітів та стану системи
Розрізняйте причини відмови за HTTP-кодом: 400 означає некоректний запит, 401 — відсутній або недійсний ключ, 402 — нестачу кредитів, 429 — обмеження частоти. Некоректні запити не списують кредити, а помилка зовнішнього сервісу повертає зарезервований кредит. Успішна порожня відповідь залишається платним отриманням даних. Окремі обробники цих випадків допомагають не плутати відсутність збігів із проблемою доступу.
Маршрут /v1/status доступний без ключа й не витрачає кредитів. Він повідомляє статичний опис історичного сервісу та підтверджує, що HTTP-сервер відповідає. Цей результат не перевіряє пошук, наявність конкретного запису або повноту архіву. Не використовуйте його як доказ справності всієї інфраструктури чи гарантію успіху наступного запиту. Для обробки результату отримання даних усе одно потрібно перевірити відповідь відповідного маршруту.
Плануючи пагінацію, враховуйте, що один запит отримує одну сторінку: limit визначає від 1 до 100 записів, page — номер від 1 до 100. Навіть повний обхід дозволеного діапазону не доводить повноти вибірки. Підсумок eq є точним числом збігів, gte — нижньою межею, unknown — відсутністю надійного підсумку, який може бути null. Не прирівнюйте нижню межу до точного підрахунку.
