독립적 아카이브 구조와 데이터 모델
Reddit Data API는 실시간 Reddit과 제휴하지 않은 독립적인 과거 아카이브입니다. 조회에는 Authorization: Bearer YOUR_API_KEY 또는 X-API-Key: YOUR_API_KEY를 사용할 수 있습니다. 둘 다 유효한 인증 방식입니다. 키와 잔액은 이 도메인 전용이며 계정 패널의 Secure HttpOnly 세션 쿠키와 조회 인증 헤더는 별개입니다. 실제 키를 브라우저 공개 코드나 적재 파일에 넣지 마세요.
API 응답은 서버에서 스레드 구조를 조립한 것이 아닌 평평한 구조의 레코드를 반환합니다. 반환된 레코드에 parent_id와 link_id 필드가 포함되어 있더라도, 이는 완전한 대화 기록이나 모든 계보 관계가 보장된다는 의미가 아닙니다. 클라이언트에서 이를 활용하여 로컬 그룹핑을 수행할 수 있지만, 완전성이나 순서를 서버 측에서 약속하지는 않습니다.
쿼리 구문에서 min_score는 점수 순서 매김을 제어하는 정렬 기준이 아닙니다. 오직 데이터 집합을 필터링하는 조건으로만 동작합니다. 또한 아카이브의 _doc 정렬 방식은 시간순, 관련도 순 또는 점수 순이 아니며, 페이지 반복을 통해 전체 데이터가 모두 수집된다는 보장은 없습니다. 정확한 데이터 포맷을 위해 로컬 처리 전략이 필요합니다.
스키마 확인은 작은 응답에서 시작하세요. /v1/posts?subreddit=python&limit=3은 최대 3개의 게시물을 요청합니다. 날짜나 본문 같은 항목이 모든 레코드에 존재한다고 가정하지 말고 실제 값을 검사하세요. 변환 규칙과 코드 버전을 원본 응답과 함께 저장하면 같은 로컬 입력으로 테스트할 수 있습니다. 이 방법은 자신의 적재 처리를 검증하며 원격 스키마나 내용이 영구히 고정된다는 뜻은 아닙니다.
엔드포인트 쿼리 필터 및 제한 사항
검색 필터는 q, subreddit, author, kind, from, to, min_score, limit, page입니다. kind는 post 또는 comment를 사용합니다. 날짜는 UTC 기준 YYYY-MM-DD이며 to 날짜도 포함됩니다. /v1/posts와 /v1/comments에는 id를 쓰지 않고, /v1/item에는 id가 필요합니다. 결과의 parent_id나 link_id는 로컬 관계 분석에 쓸 수 있지만 요청 필터가 아닙니다.
각 요청당 최대 100개 레코드, 쿼리당 최대 100페이지의 제한이 적용됩니다. /v1/subreddits 엔드포인트는 접두어(prefix) 검색을 지원하지만, /v1/posts나 /v1/comments에서는 parent_id나 link_id를 기반으로 한 서버 측 필터링은 제공되지 않습니다. 반환된 필드를 기반으로 한 로컬 그룹핑은 선택 사항이며, 서버 측 스레드 트리 또는 완전성 약속이 아닙니다.
총수 관계 eq는 정확한 값, gte는 하한, unknown은 신뢰할 수 있는 총수를 알 수 없음을 나타냅니다. 총수는 null일 수 있습니다. /v1/subreddits의 집계도 전역적으로 정확한 값이라고 보장되지 않습니다. 총수가 정확하더라도 모든 일치 기록을 클라이언트가 받았다는 의미는 아닙니다. 원본 응답과 관계 정보를 함께 저장하고, 페이지가 재요청 시에도 같을 것이라고 가정하지 마세요.
결제 모델, 에러 코드 및 검증 절차
성공한 조회는 빈 결과여도 1크레딧을 사용합니다. 유효하지 않은 요청은 차감되지 않고 상위 데이터 소스의 실패는 예약된 크레딧을 반환합니다. 클라이언트가 응답을 받지 못했더라도 서버에서 유료 성공이 발생했을 수 있습니다. 재시도가 성공하면 별도로 과금됩니다. 원본 응답을 저장한 다음 로컬 진행 상태를 갱신하면 어떤 입력을 적재했는지 확인하는 데 도움이 됩니다.
HTTP 400은 잘못된 매개변수, 401은 키 누락 또는 무효, 402는 잔액 부족, 429는 요청 속도 제한입니다. 400이면 매개변수를 수정하고 401이면 키를 확인하세요. 402이면 작업을 멈추거나 잔액을 충전하고, 429이면 기다린 뒤 다시 시도하세요. 이 코드는 처리 결과를 나타낼 뿐, 아카이브가 완전하거나 데이터 소스가 정상이라는 증거는 아닙니다.
/v1/status는 키 없이 사용할 수 있고 무료입니다. 정적인 서비스 안내와 HTTP 응답 여부만 제공하며 검색 가용성이나 특정 레코드의 존재를 검사하지 않습니다. 적재 전에는 실제 응답의 필드와 자료형을 목표 테이블과 비교하세요. 누락값 처리와 거부된 행의 이유를 기록하고, 예상치 못한 값을 조용히 변환하는 대신 검토 대상으로 보존하는 방법을 고려하세요.
