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