경로와 인증 선택
기본 호스트는 https://api.redditapiproxy.com 이며 조회에는 GET을 사용합니다. /v1/search는 검색, /v1/posts는 게시물, /v1/comments는 댓글 조회에 사용합니다. 한 항목의 식별자를 알고 있다면 /v1/item?id=... 로 조회하세요. 커뮤니티 접두어 검색에는 /v1/subreddits?prefix=... 를 사용합니다. 각 경로는 독립적인 과거 아카이브의 기록을 다루며 공식 Reddit API의 모든 경로와 동작을 대신하지 않습니다. 게시, 투표나 메시지 전송 기능은 없습니다.
인증이 필요한 조회는 Authorization: Bearer YOUR_API_KEY 또는 X-API-Key: YOUR_API_KEY 중 하나를 사용합니다. 두 헤더 모두 지원되며 Bearer라는 이름 때문에 Reddit OAuth 토큰을 넣어서는 안 됩니다. 이 도메인에서 발급한 키를 사용하세요. 자리표시자를 실제 키로 바꾸는 작업은 실행 환경에서 수행하고 공개 코드에는 비밀 값을 넣지 마세요. 계정 로그인에 쓰는 Secure HttpOnly 세션 쿠키는 이 조회 인증과 다른 역할을 합니다.
헤더 호환성을 점검할 때는 https://api.redditapiproxy.com/v1/comments?subreddit=devops&limit=3 처럼 작은 요청을 선택할 수 있습니다. 경로와 필터를 고정한 뒤 각 헤더를 별도로 시험하고 상태 코드를 확인하세요. 이 과정은 결과 내용의 동일성을 검증하는 절차가 아닙니다. 두 번 모두 성공하면 두 크레딧을 사용합니다. 빈 응답도 성공한 조회라면 과금되므로 반환된 댓글 수만으로 사용량을 계산하지 마세요.
필터와 결과 해석
검색, 게시물과 댓글 조회에서 확인할 필터는 q, subreddit, author, kind, from, to, min_score, limit, page입니다. kind에는 post 또는 comment를 사용합니다. 날짜는 UTC 기준 YYYY-MM-DD 형식이며 to는 지정한 날짜 전체를 포함합니다. min_score는 최소 점수 기준을 적용하는 필터로 점수순 정렬 지시가 아닙니다. id는 /v1/item의 매개변수이며 게시물이나 댓글 목록의 식별자 필터로 추가하면 안 됩니다.
한 요청은 최대 100개 레코드를 반환하고 한 쿼리는 최대 100페이지까지 조회할 수 있습니다. 페이지마다 별도 조회 비용이 발생하며 결과는 아카이브 문서 순서입니다. 시간순이나 관련도순이라고 해석하지 마세요. eq는 정확한 총계, gte는 하한, unknown 또는 null은 신뢰할 총계를 알 수 없는 상태입니다. 총계의 단위는 페이지가 아닌 레코드입니다. 정확한 총계를 받아도 클라이언트가 모든 결과를 저장했다는 증거는 아닙니다.
반환값은 평평한 레코드입니다. parent_id와 link_id가 있으면 관계 분석에 선택적으로 활용할 수 있지만 이 필드들은 조회 필터가 아닙니다. 일반적인 읽기나 집계를 위해 대화 트리를 구성할 필요는 없습니다. 로컬 그룹화는 빠진 상위 기록을 복원하지 않습니다. 커뮤니티 집계 건수도 전체 아카이브의 정확한 재고 목록이나 완전한 알파벳순 디렉터리로 취급하지 마세요. 실제 받은 결과의 범위와 해석상 한계를 함께 남기세요.
오류와 과금 구분
400이면 지원하지 않는 매개변수나 잘못된 날짜와 값을 먼저 수정하세요. 401이면 키의 누락, 다른 도메인의 키 사용, 재생성 후 남은 이전 키를 확인하세요. 402이면 해당 도메인 계정의 잔액을 확인해야 합니다. 429이면 호출 빈도를 줄이고 대기 간격을 둡니다. 동일한 요청을 즉시 반복하거나 다른 계정으로 제한을 피하는 방식은 문제를 해결하는 적절한 통합 절차가 아닙니다.
유효하지 않은 요청은 크레딧이 차감되지 않고 상위 시스템 실패에 대한 예약분은 반환됩니다. 반면 클라이언트 연결 종료나 응답 유실은 서버의 성공 여부를 확정하지 못합니다. 이미 성공한 조회 뒤에 응답만 유실되었을 수 있으므로 성공한 재시도에 또 크레딧이 사용될 가능성을 고려하세요. 읽기 전용이라는 특성은 비용 면에서 중복 실행이 무해하다거나 응답 내용이 고정되어 있다는 보장이 아닙니다.
/v1/status는 공개된 비과금 경로입니다. 정적인 서비스 범위와 애플리케이션의 HTTP 응답을 확인할 수 있지만 검색 저장소의 연결 상태, 특정 기록의 존재, 인증 키나 잔액을 검사하지는 않습니다. 상태 응답을 모든 조회가 가능하다는 신호로 사용하지 마세요. 실제 조회와 상태 확인을 분리하고 로그에는 비밀 키를 제외한 경로, 필터, 상태 코드와 로컬 저장 결과를 남기는 방식으로 문제 범위를 좁히세요.
