API 라우트 및 인증 체계
API Reddit CC는 독립적인 레딧 아카이브 검색 서비스를 제공합니다. 이 시스템은 레딧 공식 데이터베이스와 연결되지 않으며, 오직 과거의 레딧 데이터만 처리합니다. 주요 API 엔드포인트는 검색을 위한 /v1/search, 게시글 조회용 /v1/posts, 댓글 조회용 /v1/comments, 특정 항목 조회를 위한 /v1/item, 서브레딧 목록을 위한 /v1/subreddits, 그리고 서비스 상태를 확인하는 /v1/status로 구성됩니다. 각 라우트는 독립적으로 작동하여 유연한 데이터 접근을 지원합니다.
조회 요청은 Authorization: Bearer 또는 X-API-Key로 인증합니다. 키는 가입 직후 결제 전에 한 번 표시되며, 서버에는 원문이 아닌 해시와 접두부가 저장됩니다. API 키는 특정 테넌트 환경에 종속되므로, 다른 사이트에서 생성된 키가 네트워크 전체에서 공유되지 않습니다. 또한 OAuth 인증 방식은 지원하지 않으며, 조회에는 API 키를 사용합니다. /v1/status는 키 없이 이용할 수 있으며 계정 로그인 세션과는 별개입니다. 키는 서버 측에서 생성된 고유 값을 사용하여 접근해야 합니다.
/v1/status 엔드포인트는 정적인 아카이브 공지와 HTTP 서버의 응답 상태를 알려줍니다. 이 라우트는 검색 백엔드의 상태나 데이터 무결성을 확인하지 않으며, 오직 서버가 응답 가능한지 여부만을 나타냅니다. 상태 조회 요청은 크레딧을 차감하지 않으므로 빈번한 확인에 적합합니다. 데이터의 완전성이나 아카이브 가용성에 대한 보장은 상태 조회로 확인될 수 없습니다.
쿼리 파라미터 및 데이터 처리
검색 시 사용 가능한 주요 필터로는 검색어 q, 서브레딧 subreddit, 작성자 author, 데이터 유형인 kind(post 또는 comment), 그리고 UTC의 YYYY-MM-DD 날짜를 지정하는 from과 to(to 날짜 포함)가 있습니다. q는 title과 text를 검색하며, 여러 단어는 일치하는 같은 필드 안에서 AND 조건으로 결합합니다. min_score는 오직 필터링 용도로만 사용되며, 결과의 순서를 정렬하는 데 사용되지 않습니다. 제한(limit)과 페이지(page)는 각각 1에서 100 사이의 정수여야 하며, 최대 100개의 기록을 한 번의 요청으로 조회할 수 있습니다.
특히 item 유형인 /v1/item 라우트에서는 id 파라미터가 필수입니다. 반면에 /v1/posts와 /v1/comments 라우트는 id 파라미터를 필요로 하지 않습니다. 이는 전체 아카이브 내에서 게시글과 댓글을 광범위하게 검색할 때 유용합니다. 서브레딧 라우트는 prefix 입력을 지원하므로, 앞부분이 일치하는 서브레딧 이름을 사용하여 관련 서브레딧 목록을 효율적으로 가져올 수 있습니다. 필터 조건에 일치하는 레코드만 반환되며, 명시된 필터 외의 조건은 적용되지 않습니다.
응답의 총 개수는 페이지 정보에서 확인할 수 있으며, 이는 eq(정확한 수), gte(하한), 또는 unknown(총수 불명, null 가능) 세 가지 관계 중 하나로 표시됩니다. 하한선 값은 정확한 총 개수가 아님을 의미하므로, 전체 아카이브의 모든 결과가 포함되어 있다고 가정하면 안 됩니다. 페이지 반복이 아카이브의 완전한 인덱싱이나 모든 일치 항목의 수집을 보장하지 않으므로, 데이터 양이 많을 때는 주의해야 합니다. 데이터는 아카이브의 내부 문서 순서로 반환됩니다.
응답 구조 및 오류 처리
API 응답은 플랫 형식의 개별 레코드 목록을 반환하며, 서버에서 스레드 트리를 직접 조립하지 않습니다. 응답 데이터에 parent_id나 link_id 필드가 포함되어 있더라도, 클라이언트 측에서 이를 그룹화하는 것은 옵션입니다. 서버는 완전한 대화나 모든 부모 기록의 존재를 보장하지 않습니다. 로컬에서 묶더라도 빠진 관계가 채워지는 것은 아니며, 완전한 스레드가 재구성된다고 볼 수 없습니다.
오류 처리는 HTTP 상태 코드를 통해 명확히 구분됩니다. 400은 잘못된 요청을, 401은 누락되거나 잘못된 API 키를 나타내며, 402는 크레딧이 부족함을 의미합니다. 또한 429 코드는 너무 많은 요청이 제출되었음을 나타냅니다. 원천 서비스의 실패는 예약한 크레딧을 사용자 잔액에 돌려주며, 잘못된 요청은 차감하지 않습니다. 성공적인 빈 결과 조회 또한 하나의 크레딧이 부과되며, 이는 오류 환불 정책과 대조됩니다. HTTP 상태 코드는 ASCII 숫자로 표시됩니다. 클라이언트가 응답을 잃었더라도 서버는 이미 성공해서 크레딧을 사용했을 수 있으며, 성공한 재시도는 크레딧을 하나 더 사용합니다.
이 API 서비스는 레딧 공식 서비스가 아니며, SLA나 성능 벤치마크를 보장하지 않습니다. 데이터는 아카이브 순서로 반환되므로 시간순이나 관련성 순이 아닐 수 있습니다. 데이터의 완전한 수집이나 아카이브의 영속성에 대한 보장은 제공되지 않습니다. 이 서비스는 독립적 아카이브의 성격을 유지하며, 레딧의 현재 라이브 데이터와는 구분됩니다. 사용자는 API 키를 안전하게 관리하고 적용되는 법률을 준수해야 합니다.
