Автентифікація та результати звернень
Надсилайте GET-запити до https://api.subredditapi.com із заголовком X-API-Key: <ключ> або Authorization: Bearer <ключ>. Обидва варіанти підтримуються. Зберігайте секрет у конфігурації серверного клієнта, а не у відкритому наборі даних чи діагностичному журналі. Панель облікового запису використовує окремий Secure HttpOnly cookie для сесії. Вхід у панель не замінює заголовок ключа, потрібний для отримання записів дослідницьким застосунком.
HTTP 400 означає некоректний запит, 401 — відсутній або недійсний ключ, 402 — недостатню кількість кредитів, 429 — обмеження частоти. Після 400 виправляйте параметри, після 401 перевіряйте секрет, після 402 призупиняйте збір або вирішуйте питання поповнення. Для 429 передбачте очікування та межу повторів. Перевіряйте статус перед розбором тіла відповіді як чергової успішної сторінки, щоб повідомлення про помилку не потрапило до дослідницької таблиці.
Успішний запит списує один кредит, навіть якщо збігів немає. Некоректні запити не зменшують баланс, а збій зовнішнього сервісу повертає зарезервований кредит. Помилка з’єднання клієнта може виникнути після успішного платного отримання даних сервером; інша успішна спроба оплачується окремо. У журналі розрізняйте спроби звернень, фактично отримані сторінки й записи, прийняті до вибірки. Локальне відхилення нерелевантного тексту не скасовує вартість успішної операції API.
Маршрути й точні фільтри
Доступні /v1/search, /v1/posts, /v1/comments, /v1/item, /v1/subreddits і /v1/status. Пошук застосовує підтримувані текстові умови, а маршрути дописів і коментарів обирають відповідний тип записів. Лише /v1/item потребує id відомого елемента; id не є фільтром дописів або коментарів. Для знайомства з назвами спільнот використайте /v1/subreddits із prefix та limit, не вважаючи агреговані кількості глобально точними.
Параметри пошуку: q, subreddit, author, kind, from, to, min_score, limit і page. kind приймає post або comment. Дати задаються як YYYY-MM-DD в UTC, причому день to входить у діапазон. min_score відсіює записи нижче числового порога, але не сортує. Довільна мова запитів, серверна оцінка тональності та користувацька аналітика не надаються. Аналіз отриманого тексту відбувається у ваших власних інструментах після завантаження.
Відповіді містять плоскі записи без зібраного сервером дерева обговорення. Якщо parent_id або link_id присутні, клієнт може локально згрупувати отримані об’єкти, але всі предки та повна розмова не гарантуються. Фільтри за цими двома полями відсутні. У прикладі soil задає пошуковий текст, gardening — одну спільноту, limit=3 — максимум три записи. Для другої групи виконайте окремий запит і зафіксуйте змінений параметр, зберігаючи інші умови порівняння.
Пагінація й тлумачення підсумків
Параметри limit і page мають діапазон від 1 до 100. Один запит отримує одну сторінку максимум зі 100 записами, а не сто сторінок одночасно. Внутрішній порядок документів _doc не відповідає хронології, релевантності чи оцінці. Локальне сортування впорядковує лише отримані об’єкти. Завершення всіх дозволених сторінок не гарантує повного переліку збігів або відсутності повторів між збереженими частинами дослідницької вибірки.
Підсумок потрібно читати разом із relation: eq означає точну кількість збігів запиту, gte — нижню межу, unknown — відсутність надійного підсумку, який може бути null. Нижня межа не є точним числом. Навіть точний лічильник не доводить, що клієнт отримав усі матеріали. Поділ запитів за датами допомагає організувати роботу, але не підтверджує повноти охоплення або відсутності перетинів між наборами.
Зберігайте фактичні відповіді, параметри, час отримання й версію локального опрацювання. Це допомагає пояснювати склад вибірки та повторювати аналіз уже завантажених файлів. Віддалений повтор не обіцяє тих самих записів. Публічний /v1/status не потребує ключа й не тарифікується; він повертає статичний опис історичного сервісу та відповідь HTTP-застосунку. Пошук, наявність конкретного матеріалу, навантаження і швидкість отримання записів цей маршрут не перевіряє.
