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