인증 및 권한 관리
보호된 조회에는 Authorization: Bearer YOUR_API_KEY 또는 X-API-Key: YOUR_API_KEY를 사용할 수 있습니다. 둘 다 유효하며 /v1/status는 공개이고 키 없이 무료입니다. 키와 잔액은 redditcommentsapi.com에서만 유효합니다. 키는 가입 직후 결제 전에 한 번 표시되며 로그인 후 비밀번호 확인으로 교체할 수 있습니다. 재생성은 이전 API 키를 즉시 무효화하지만 계정 세션을 끊는 것과는 다릅니다. 실제 키를 공유 연구 파일이나 공개 코드에 넣지 마세요.
HTTP 400은 잘못된 요청, 401은 키 누락 또는 무효, 402는 잔액 부족, 429는 요청 속도 제한입니다. 잘못된 요청은 차감하지 않고 상위 데이터 소스 실패는 예약 크레딧을 반환합니다. 클라이언트가 응답을 놓쳐도 서버의 과금된 성공이 있었을 수 있습니다. 성공한 재시도는 새 크레딧을 사용하며 빈 결과의 성공도 1크레딧입니다. 매개변수와 키를 수정하거나 잔액을 검토하고 속도 제한에서는 기다리세요.
/v1/status는 정적인 서비스 안내와 HTTP 서버의 응답만 나타냅니다. 검색 상태, 기록의 가용성, 키 또는 쿼리를 검사하지 않습니다. 무료 상태 요청의 성공이 실제 조회의 성공을 보장하는 것은 아닙니다. 받은 조회 응답을 검증하고 저장한 뒤 로컬 진행 상태를 갱신하세요. 계정 로그인은 Secure HttpOnly 쿠키를 쓰고 조회 키 헤더와 별개입니다. localStorage의 사용자와 청구서 ID는 청구서 복구용이며 원본 키는 그곳에 영구 저장하지 않습니다.
사용 가능한 라우트 및 필터
검색 필터는 q, subreddit, author, kind, from, to, min_score, limit, page입니다. kind는 post 또는 comment를 사용합니다. 날짜는 UTC 기준 YYYY-MM-DD이며 to 날짜도 포함합니다. q는 텍스트 검색이지 감정 분석이 아닙니다. /v1/item은 알려진 기록의 id를 요구하지만 /v1/posts와 /v1/comments 목록에는 id를 사용하지 않습니다. 커뮤니티의 일부 댓글을 조회하는 것과 특정 게시물의 모든 답글을 받는 것을 구별하세요.
/v1/subreddits는 prefix와 limit로 커뮤니티 이름을 찾습니다. 이 경로는 대화의 부모를 탐색하지 않으며 집계 수도 전역적으로 정확하다고 보장하지 않습니다. /v1/comments에는 parent_id나 link_id 필터가 없습니다. 시작 예시는 /v1/comments?subreddit=learnprogramming&limit=3으로 최대 3개를 요청합니다. 3개의 존재나 서로 연결된 대화가 보장되지 않으므로 응답에 있는 관계 필드만 로컬 처리에 활용하세요. 없는 부모와 문맥을 추정으로 채우지 마세요.
요청당 최대 100개 레코드, 쿼리당 최대 100페이지를 사용할 수 있습니다. eq는 정확한 일치 기록 수, gte는 하한, unknown은 신뢰할 총수를 알 수 없음을 나타내며 총수가 null일 수 있습니다. 이는 총 페이지 수가 아닙니다. 하한을 정확한 값으로 해석하지 말고 정확한 총수도 모두 저장했다는 증거로 쓰지 마세요. 페이지 반복이나 구간 분할은 완전하거나 중복 없는 수집을 보장하지 않습니다.
데이터 구조 및 정렬 규칙
응답은 서버가 조립한 대화 트리가 아닌 평면 레코드입니다. parent_id와 link_id가 있다면 로컬로 관계를 만들 수 있지만 전체 선행 발화나 대화가 보장되지는 않습니다. 필드 자료형을 확인하고 부모가 없는 경우 미해결로 남기세요. 중복 식별자, 자기 참조와 순환이 있다면 로컬 검증에서 별도로 다룹니다. 이는 클라이언트 처리 제안이지 API의 자동 복원 기능이 아닙니다. 시각화가 완전한 대화의 증거가 되지는 않습니다.
min_score는 결과를 걸러낼 뿐 정렬하지 않습니다. 문서 순서는 시간순, 관련도순, 점수순이 아니고 저장 시각의 순서라고 추정할 근거도 없습니다. 응답, 요청 조건과 로컬 분석 버전을 함께 저장하면 같은 입력을 다시 처리할 수 있습니다. 그렇다고 원격 자료가 고정되어 있거나 미래 조회가 같다는 의미는 아닙니다. 논의의 의미는 실제 인용에 근거해 해석하고 모호한 부분과 제외 이유를 기록하세요.
post와 comment는 id 없이 조회되지만, item만 id를 필요로 합니다. 또한, parent_id나 link_id를 기반으로 한 명시적인 쿼리 필터는 현재 노출되어 있지 않습니다. 데이터의 완전성을 가정하지 않고, 반환된 필드만 기준으로 로컬에서 처리하는 것이 권장됩니다. 이 구조는 대화가 어떻게 연결되어 있는지를 클라이언트 단에서 재구성할 수 있게 해줍니다.
