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