경로와 인증
기본 주소는 https://api.redditfetch.com 입니다. GET /v1/search는 게시물과 댓글을 검색하고 /v1/posts는 게시물, /v1/comments는 댓글을 조회합니다. GET /v1/item?id=...에서는 특정 기록의 식별자를 지정합니다. id는 item 전용이며 posts나 comments에서 지원하는 필터가 아닙니다. GET /v1/subreddits?prefix=...는 커뮤니티 이름의 시작 부분으로 조회합니다. 커뮤니티 집계 건수가 전체 아카이브에 대해 항상 정확하다는 보장은 없습니다.
조회 인증에는 Authorization: Bearer YOUR_API_KEY와 X-API-Key: YOUR_API_KEY가 모두 지원됩니다. 하나를 선택하고 실제 키는 서버의 비밀 설정에서 읽으세요. 계정 패널의 Secure HttpOnly 세션 쿠키는 다른 용도이며 API 키 헤더를 대신하지 않습니다. 계정, 키와 잔액은 이 도메인 전용입니다. 다른 브랜드의 키로 redditfetch.com의 같은 계정에 접근할 수 있다고 가정하지 마세요.
GET /v1/status는 공개되어 있고 크레딧을 사용하지 않습니다. 고정된 서비스 범위 설명과 HTTP 애플리케이션이 응답한다는 사실을 보여 줍니다. 아카이브 소스, 쿼리 동작, 기록 존재나 잔액을 검사하지는 않습니다. 상태 응답이 성공했다고 다음 데이터 조회도 성공한다고 판단하지 마세요. 실제 데이터 요청의 상태와 내용을 각각 처리하고 필요한 기록을 받았는지 확인해야 합니다.
필터와 페이지 처리
검색, 게시물과 댓글에는 q, subreddit, author, kind, from, to, min_score, limit, page를 사용할 수 있습니다. kind 값은 post 또는 comment입니다. 날짜는 UTC 기준 YYYY-MM-DD 형식이며 to 날짜도 포함됩니다. min_score는 최소 점수 조건이지 정렬 옵션이 아닙니다. parent_id와 link_id는 조회 필터가 아니므로 이를 붙여 대화 전체를 요청할 수 있다고 생각하지 마세요.
limit은 1~100, page는 1~100을 받습니다. 한 요청은 최대 100개 기록이고 한 쿼리는 최대 100페이지입니다. 각 페이지는 별도로 요청합니다. 결과는 아카이브 문서 순서이며 시간, 관련도나 점수 순서가 아닙니다. 페이지 반복이나 날짜 구간 분할은 전체 수집이나 중복 없는 결과를 보장하지 않습니다. 사용한 조건과 실제 저장한 페이지를 자체 작업 기록으로 남겨 받은 범위를 설명하세요.
전체 건수는 페이지 수와 다릅니다. eq는 정확한 건수, gte는 하한, unknown이나 null은 신뢰할 수 있는 전체 건수가 없음을 뜻합니다. 정확한 건수도 클라이언트가 전부 저장했다는 증거는 아닙니다. 응답은 평면 기록입니다. 읽기와 개수 세기에는 트리가 필요 없으며 관계를 조사할 때만 존재하는 parent_id나 link_id로 선택적 로컬 그룹화를 할 수 있습니다. 누락된 부모나 댓글을 복원하지는 않습니다.
HTTP 오류와 비용 구분
HTTP 400은 조건의 형식이나 값을 확인해야 하는 경우입니다. HTTP 401은 키가 없거나 유효하지 않음, HTTP 402는 잔액 부족, HTTP 429는 요청 속도 제한을 뜻합니다. Node.js에서는 이런 HTTP 응답과 네트워크 문제로 promise가 거부되는 경우를 구분하세요. response.ok와 response.status를 확인해 처리합니다. 조건과 키는 수정하고 속도 제한에서는 새 요청을 늦추는 방식으로 원인에 맞게 대응해야 합니다.
성공한 조회는 빈 결과도 한 크레딧을 사용합니다. 잘못된 요청은 차감하지 않고 상위 소스 장애에서는 예약한 크레딧을 돌려줍니다. 그러나 클라이언트의 연결이 끊어져도 서버에서는 유료 요청이 성공했을 수 있습니다. 이후 성공한 재시도는 추가 비용입니다. 비밀 헤더를 기록하지 않으면서 상태와 자체 작업 식별자를 추적하면 재시도 판단에 도움이 될 수 있습니다. 통신 오류 표시만으로 비용이 없었다고 결론 내리지 마세요.
