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