날짜 구간을 로컬 작업으로 정의
Reddit Stream API는 독립적인 과거 아카이브이며 SSE나 WebSocket 실시간 스트림이 아닙니다. 정기 조회를 하더라도 최신 Reddit 이벤트가 즉시 도착하지 않으며 갱신 일정이나 결과 불변성도 보장되지 않습니다. 여기서 증분 처리는 자체 배치를 추적할 수 있는 작은 작업으로 나눈다는 뜻입니다. 서버의 이벤트 커서, 전달 보장이나 완전한 변경 목록이 아닙니다. 사용자에게는 실제로 받은 과거 기록의 처리라고 설명하세요. 읽기 전용이라는 이유로 통신 실패나 응답 변경이 사라지는 것도 아닙니다.
필요에 맞으면 /v1/search나 /v1/posts의 from과 to로 날짜를 나눌 수 있습니다. UTC 기준 YYYY-MM-DD이며 to는 지정한 날짜 전체를 포함합니다. 종료일을 다음 작업의 시작일로도 쓰면 겹치는 구간을 만들 수 있으므로 일 단위 계획에서 이 규칙을 고려하세요. 초 단위 지정이 가능하다고 가정하지 마세요. 구간을 규칙적으로 나누어도 각 날짜의 기록이 존재하거나 모든 일치 결과를 받을 수 있다는 증거는 아닙니다. 전체 수집이라는 표현은 작업 분할만으로 정당화되지 않습니다.
기간을 자체 작업 식별자와 연결하면 어떤 조건으로 몇 페이지를 시도했는지 확인할 수 있습니다. 이는 장애 조사와 우선순위 설정을 위한 클라이언트의 방법이며 서버의 고정 데이터셋은 아닙니다. 문서 순서가 시간순이 아니므로 마지막 레코드의 날짜를 그 이전 기간의 수집 완료 경계로 사용하지 마세요. 로컬에서 시간순으로 정렬하더라도 정리되는 것은 받은 기록뿐이며 아직 받지 않은 데이터는 발견되지 않습니다. 진행 상태와 결과 범위의 설명을 분리해 남겨야 합니다.
페이지 저장과 재개 조건
페이지 요청 예제는 https://api.redditstreamapi.com/v1/posts?subreddit=datasets&limit=3&page=2 입니다. 쿼리당 최대 100페이지, 요청당 최대 100개 레코드라는 한도가 있으며 limit은 필요에 따라 선택합니다. 항상 100을 쓸 의무는 없습니다. 페이지 번호는 문서 순서의 선택이지 영구 이어받기 위치나 타임스탬프가 아닙니다. 두 번째 페이지나 세 개의 기록을 약속하는 예제도 아니고 저장한 번호에서 같은 스냅샷이 재개된다는 보장도 없습니다. 받은 결과를 다음 날짜 경계로 임의로 바꾸어 해석하면 안 됩니다.
각 시도에서 조건, 페이지, 시도 시각, HTTP 결과와 로컬 쓰기 결과를 따로 남기세요. 응답 성공 뒤 저장이 실패하면 번호만 올릴 경우 미저장 결과를 건너뛸 수 있습니다. 다시 실행하기 전에 파일이나 데이터베이스를 확인하세요. 이 진행 기록은 자체 작업 상태이며 서버에서 누락 없이 재개된다는 보장이 아닙니다. 한도 때문에 멈춘 작업과 실제로 받은 결과의 처리가 끝난 작업도 구분해 보고하세요. 번호 기록만으로 전체 아카이브 수집이 완료됐다고 선언해서는 안 됩니다.
결과는 시간순, 관련도순이나 점수순이 아닙니다. min_score는 최소 점수 조건일 뿐입니다. eq는 정확한 레코드 총계, gte는 하한, unknown 또는 null은 신뢰할 총계를 알 수 없는 상태입니다. 정확한 수라도 전량 저장을 증명하지 않습니다. parent_id와 link_id로 묶는 것은 관계 분석을 위한 선택 사항이며 읽기나 집계에는 필요하지 않습니다. 빠진 부모도 복구되지 않습니다. 날짜 분할과 중복 제거는 전체 범위와 수집의 유일성을 입증하지 않으므로 실제 받은 페이지를 기준으로 결과를 설명하세요.
인증, 오류와 재시도 예산
Authorization: Bearer YOUR_API_KEY 또는 X-API-Key: YOUR_API_KEY를 사용합니다. 두 형식은 이 도메인의 아카이브 키를 사용하며 Reddit OAuth 토큰이 아닙니다. 비밀 값은 서버에 두고 로그에서 제외하세요. 400은 매개변수 수정, 401은 키 확인, 402는 잔액 확인, 429는 빈도 감소와 대기가 필요할 수 있습니다. 시도 상한을 정하고 다른 계정으로 제한을 피하지 마세요. 브라우저의 계정 세션이 배치의 헤더 설정을 검증해 주지는 않으므로 실행 프로세스의 구성도 확인해야 합니다.
성공한 조회는 빈 결과도 한 크레딧이며 성공 요청 1,000건은 $1입니다. 유효하지 않은 요청은 차감되지 않고 상위 시스템 실패의 예약분은 반환됩니다. 클라이언트의 응답 유실은 서버 실패를 뜻하지 않으며 성공한 재시도에는 추가 비용이 생길 수 있습니다. 저장 상태와 예산에 따라 반복을 제한하세요. 읽기 전용이어도 같은 응답이나 무료 반복이 보장되지 않습니다. 로컬 응답의 재처리와 아카이브에 새 요청을 보내는 것은 다른 작업이므로 기록과 비용 계산에서 따로 취급해야 합니다.
/v1/status는 공개 비과금 경로이지만 정적인 범위와 HTTP 응답만 알리고 검색, 기록, 키와 잔액을 검사하지 않습니다. 이 응답만으로 수집 완료 상태를 만들지 마세요. 작업 보고서에는 시도한 페이지, 저장한 결과, 중단 이유와 범위의 불확실성을 적을 수 있습니다. 그래도 아카이브의 완전성, 영구 보존이나 일정한 성능을 증명하지는 않습니다. 결과를 이용하거나 표시할 때 적용되는 법률과 제삼자의 권리도 고려해야 합니다. 이러한 보고는 실시간 이벤트를 빠짐없이 전달했다는 확인서가 아닙니다.
