사용자의 질문을 매개변수로 바꾸세요
앱이 어떤 질문에 답할 것인지 먼저 정하세요. 한 커뮤니티의 제품 논의를 찾는 작업과 특정 작성자의 댓글을 살펴보는 작업은 필요한 조건이 다릅니다. 검색어는 q, 커뮤니티는 subreddit, 작성자는 author에 전달하세요. 결과 가까이에 활성 조건을 표시하면 사용자가 자료 선택의 근거를 이해하고 범위를 바꾸기 쉽습니다. 지원하지 않는 자체 검색 문법을 사용할 수 있는 것처럼 보여 주지 마세요.
날짜 선택 결과는 UTC 기준 YYYY-MM-DD로 변환합니다. from은 시작일이며 to는 선택한 종료일을 포함합니다. 화면에 지역 날짜를 표시할 경우에도 API에 전달되는 실제 경계를 설명하세요. 게시글만 필요하면 kind=post, 댓글만 필요하면 kind=comment입니다. min_score는 최소 점수 조건일 뿐 인기순 정렬 요청이 아닙니다. 높은 점수의 기록만 선택하면 표본이 달라진다는 점도 분석에서 고려하세요.
검색 양식에는 독립적인 과거 아카이브를 이용한다고 명시하세요. 실시간 갱신, Reddit과의 공식 관계, 전체 이력의 완전한 검색을 약속하지 마세요. 좁은 조건도 관련 기록 전체를 보장하지 않습니다. 사용자가 조사하려는 대상과 실제로 받은 표본을 구분하면, 화면에 보이는 일부 기록만으로 전체 커뮤니티에 대한 결론을 내리는 일을 줄이는 데 도움이 됩니다.
조회한 범위에 맞춰 결과를 보여 주세요
GET /v1/search 또는 목적에 따라 /v1/posts와 /v1/comments를 사용하고 X-API-Key 헤더로 인증합니다. limit와 page는 1부터 100까지입니다. 호출 한 번은 최대 100개 기록의 한 페이지를 반환합니다. 다음 페이지는 별도로 요청하세요. 허용된 모든 페이지를 무조건 자동 조회할 필요는 없으므로, 사용자의 필요와 앱 예산을 고려하여 페이지 이동 방식을 결정하는 것이 좋습니다.
기록은 내부 _doc 순서로 반환되며 시간순이나 관련도순이 아닙니다. 로컬에서 날짜순으로 정렬한다면 이미 받은 기록 안에서의 정렬이라고 표시하세요. 모든 기록에 동일한 필드가 있다고 가정하지 말고 존재 여부를 확인하여 화면을 구성합니다. parent_id와 link_id가 있을 때 관계를 묶을 수 있지만, 완전한 대화 트리를 표시하고 있다고 주장해서는 안 됩니다.
eq는 정확한 쿼리 일치 개수, gte는 최소한 그 개수 이상, unknown은 전체 개수 불명으로 표시하세요. 하한값을 마지막 페이지의 증거로 사용하지 마세요. 100페이지를 반복해도 전체 일치 기록을 보장하지 않습니다. 여러 쿼리로 나누어 수집할 때에도 중복과 누락이 없다고 단정하지 말고, 로컬 처리 방식과 조회 범위를 기록하여 한계를 설명해야 합니다.
오류 처리와 분석 근거를 함께 남기세요
400에서는 매개변수, 401에서는 키와 헤더, 402에서는 잔액을 확인합니다. 429에는 대기 시간을 둔 재시도와 반복 횟수 상한을 사용하세요. /v1/status는 정적인 설명과 HTTP 응답만 제공하며 검색 엔진이나 자료 준비 상태를 검사하지 않습니다. 연결이 된다는 사실과 원하는 검색이 성공한다는 사실을 같은 상태 표시로 합치지 않는 것이 좋습니다.
성공한 호출은 비어 있어도 1크레딧입니다. 상위 서비스 실패에는 예약분이 반환되지만 클라이언트 연결 단절이 서버 성공 후 발생하면 이미 과금되었을 수 있습니다. 성공한 재시도도 유료입니다. 원본 응답과 검색 조건, 로컬 변환 코드를 함께 저장하면 다음 API 결과가 달라지더라도 이전 분석에서 사용한 자료와 처리 과정을 다시 설명할 수 있습니다.
검색 조건만 저장하는 것과 분석에 사용한 실제 기록을 저장하는 것은 다릅니다. 같은 조건의 재조회가 같은 결과를 보장하지 않기 때문입니다. 날짜 변환, 제외한 기록의 기준, 로컬 정렬 방식도 함께 문서화하세요. 이렇게 하면 다른 개발자가 앱의 동작을 검토할 때 서버 조회의 한계와 로컬 분석의 선택을 구분하고 결과를 더 정확히 해석할 수 있습니다.
