Захищене читання та публічний статус
Захищене читання використовує GET на https://api.redditdatastream.com з X-API-Key: <ключ> або Authorization: Bearer <ключ>. Обидва варіанти передають ключ архіву цього домену, а не токен Reddit OAuth. Зберігайте секрет на сервері. Cookie Secure HttpOnly панелі облікового запису стосується окремої сесії. Сервіс повертає окремі JSON-відповіді, а не живий SSE-потік, з’єднання WebSocket чи підписку на події Reddit.
/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 для пошуку назв спільнот, без посторінкового обходу та гарантії глобально точних лічильників. /v1/status публічний і безоплатний: статичний опис підтверджує відповідь HTTP-застосунку, не перевіряючи доступності пошуку, свіжості записів, чинності ключа чи балансу.
Дати, порядок документів і локальна серіалізація
from і to приймають YYYY-MM-DD в UTC та фільтрують created_utc, а не мить потрапляння запису до архіву. Останній день to включений повністю. Це фільтри днів, а не значення курсора з точністю до часу доби. Під час поділу роботи за датами зберігайте фактичні межі й розрізняйте час обробки завдання та створення запису. Поділ не доводить повноти отримання чи розкладу оновлення архіву.
min_score задає числовий поріг оцінки без сортування або визначення якості поради. Порядок _doc — внутрішній порядок документів, не час вставлення, хронологія, релевантність чи оцінка. Останній запис сторінки не є гарантованою часовою позначкою прогресу. Локальне сортування організує отримане, але не доводить, що всі раніші записи вже завантажені, а пізніші з’являться в майбутньому зверненні.
Повернуті записи є пласкими, а не зібраними сервером у дерева потоків. Якщо у записах присутні поля parent_id та link_id, клієнт може згрупувати їх локально, проте гарантії повної ієрархії чи наявності всіх зв'язків немає. Фільтрів link_id чи parent_id на рівні API-запиту не існує, тому розбиття розмов відбувається на стороні клієнта. Відповідь містить data, pagination і credits. Поля можуть різнитися або бути відсутніми. Ваш застосунок може серіалізувати окремі записи data в локальний JSONL, зберігаючи метадані окремо. Це локальна обробка, не серверний потік чи перемикач формату експорту.
Межі сторінок, підсумки та обробка збоїв
Маршрути вмісту приймають limit і page від 1 до 100, по одній сторінці за запит. page=3 не повертає трьох сторінок разом. Нумерація не є стабільним курсором чи послідовністю подій; page=101 для тієї самої вибірки не підтримується. Поділ вікон і локальне усунення дублікатів організують роботу без доведення повного охоплення, унікальності чи незмінності повторного результату. Локальна контрольна точка не гарантує продовження без втрат.
Читайте pagination.total разом із relation: eq — точний підсумок запиту, gte — нижня межа, unknown — відсутність надійного підсумку, можливо null. Порожня сторінка після першої може повернути unknown, а не число нуль. Точний підсумок не доводить завантаження всіх збігів або наявності всієї історії в архіві. Зберігайте has_more та window_exhausted як ознаки меж, не токени необмеженого експорту.
HTTP 400 стосується неправильних параметрів, 401 — відсутнього або недійсного ключа, 402 — нестачі кредитів, 429 — обмеження частоти. Некоректні запити не списуються; збій джерела повертає резерв. Успішне отримання коштує один кредит, навіть порожнє й повторне. Втрата відповіді може приховувати оплачений успіх; локальна помилка не повертає його вартості. Збережіть відповідь до оновлення прогресу та враховуйте успішні повтори окремо.
