Захищене читання та публічний статус
Захищене читання використовує GET на https://api.redditapilabs.com з X-API-Key: <ключ> або Authorization: Bearer <ключ>. Обидва варіанти передають ключ архіву цього домену, а не токен Reddit OAuth. Зберігайте секрет на сервері й виключайте його з відкритих дослідницьких журналів. Cookie Secure HttpOnly кабінету стосується окремої сесії. Ключ показують один раз одразу після реєстрації, до оплати; додаткового підтвердження ключа немає.
/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 допускають локальне групування без повного ланцюжка батьківських записів або розмови. Ці ідентифікатори не є фільтрами запиту. Відповіді містять data, pagination і credits. Перевіряйте отримані дані та позначайте відсутні поля й нерозв’язані посилання у власній таблиці. Зберігайте власні мітки та перетворення окремо від вихідного тексту, замість підставляння значень, яких не було у відповіді.
Межі сторінок, підсумки та обробка збоїв
Маршрути вмісту приймають limit і page від 1 до 100, по окремому запиту на кожну сторінку. Серія звернень не гарантує 10000 різних записів або повного набору. page=101 для тієї самої вибірки не підтримується. Поділ дат і локальне усунення дублікатів організують роботу без підтвердження вичерпного отримання. Локальний ідентифікатор запуску чи хеш файла не є серверним токеном знімка.
Читайте pagination.total разом із relation: eq — точний підсумок запиту, gte — нижня межа, unknown — відсутність надійного підсумку, можливо null. Порожня сторінка після першої може повернути unknown, а не число нуль. Точний підсумок не доводить завантаження всіх збігів або наявності всієї історії в архіві. Зберігайте has_more та window_exhausted як ознаки меж, не токени необмеженого експорту.
HTTP 400 стосується неправильних параметрів, 401 — відсутнього або недійсного ключа, 402 — нестачі кредитів, 429 — обмеження частоти. Некоректні запити не списуються; збій джерела повертає резерв. Успішне отримання коштує один кредит, навіть порожнє й повторне. Втрата відповіді може приховувати оплачений успіх; локальна помилка не повертає його вартості. Збережіть відповідь до оновлення прогресу та враховуйте успішні повтори окремо.
