첫 요청
서버에서 요청을 보내고 API 키를 비공개로 유지하세요.
: "${REDDITAPP_API_KEY:?Set REDDITAPP_API_KEY on your server}"
curl --get --fail-with-body 'https://api.redditapp.com/v1/search' \
-H "Authorization: Bearer ${REDDITAPP_API_KEY}" \
--data-urlencode 'q=offline maps' \
--data-urlencode 'subreddit=hiking' \
--data-urlencode 'limit=3'API 참조
↔ 표를 가로로 스크롤하세요
API 엔드포인트
| 메서드 | 엔드포인트 | 매개변수 |
|---|---|---|
GET | /v1/search | q, subreddit, author, kind, from, to, min_score, limit, page |
GET | /v1/posts | q, subreddit, author, kind, from, to, min_score, limit, page |
GET | /v1/comments | q, subreddit, author, kind, from, to, min_score, limit, page |
GET | /v1/item | id |
GET | /v1/subreddits | prefix, limit |
GET | /v1/status | — |
추가 참고 사항
GET | /v1/search · /v1/posts · /v1/comments · /v1/item · /v1/subreddits · /v1/status |
|---|---|
q · subreddit · author · kind | kind: post | comment |
from · to | YYYY-MM-DD |
min_score | score ≥ min_score |
limit · page | 1…100 · 1…100 |
/v1/item | id |
/v1/subreddits | prefix · limit |
_doc | ≠ date · ≠ relevance · ≠ score |
pagination.relation | eq · gte · unknown |
pagination | has_more · window_exhausted · truncated |
1 credit | $0.001 |
$1 | 1000 credits |
$50 | 50000 credits |
400 · 401 · 402 · 429 · 502 | HTTP |
앱과 아카이브 사이에 자체 백엔드를 두세요
설명용 하이킹 기능에서 모바일 또는 웹 클라이언트는 offline maps라는 문구를 자체 백엔드에 보냅니다. 백엔드는 요청을 검증하고 앱의 제한을 적용한 뒤 저장된 서비스 키로 아카이브를 호출합니다. 읽기 화면에 필요한 필드만 반환하세요. 이는 설계의 출발점이며, 이 테넌트에서 하이킹 레코드를 실제로 조회했다는 주장이 아닙니다.
GET https://api.redditapp.com/v1/search?q=offline%20maps&subreddit=hiking&limit=3&page=1을 사용하세요. 백엔드에서 X-API-Key: YOUR_SAVED_KEY 또는 Authorization: Bearer YOUR_SAVED_KEY를 헤더로 보냅니다. 인증 정보를 URL, 클라이언트 배포 코드, 공개 로그에 넣지 마세요. 계정 페이지의 세션 쿠키는 조회 인증을 대신하지 않습니다.
서비스가 실제로 받는 필터를 선택하세요
검색은 q, subreddit, author, kind, from, to, min_score, limit, page를 받습니다. q는 title과 text를 대상으로 AND 검색을 수행하며, 정확한 구문 일치나 의미 기반 일치를 보장하지 않습니다. kind에는 post 또는 comment를 지정할 수 있습니다. subreddit과 author는 해당 필드의 정확한 값으로 거르는 필터입니다. min_score는 레코드를 필터링하며 정렬하지 않습니다.
from과 to에는 UTC 기준 YYYY-MM-DD 날짜를 사용하세요. to에는 해당 UTC 날짜 전체가 포함됩니다. 예를 들어 from=2025-01-01과 to=2025-12-31은 날짜 범위를 지정하지만 날짜순 정렬을 요청하지는 않습니다. ISO 날짜·시간 문자열, 임의의 쿼리 DSL, sort 매개변수, parent_id/link_id 필터를 보내지 마세요. 지원하지 않는 매개변수는 거부됩니다.
작업에 맞는 엔드포인트를 고르세요
GET /v1/posts와 GET /v1/comments는 레코드 종류를 제한하고 검색 필터를 받으며, id를 필수로 요구하지 않습니다. GET /v1/item?id=RECORD_ID는 조회 가능한 레코드를 id로 찾습니다. GET /v1/subreddits?prefix=hik&limit=3은 범위가 제한된 subreddit 집계를 반환합니다. 그 집계 수가 아카이브 전체에서 정확하다고 보장하지는 않습니다.
GET /v1/status는 공개되어 있고 크레딧을 사용하지 않습니다. 과거 아카이브라는 고정 안내를 반환하고 HTTP 처리기가 응답한다는 사실을 보여 줍니다. 검색 백엔드를 조회하거나 콘텐츠 수록 범위를 확인하거나 아카이브 상태를 측정하지 않습니다. 어떤 엔드포인트도 게시, 투표, 메시지, 계정 북마크 또는 완전한 대화 트리를 제공하지 않습니다.
더 보기를 만들기 전에 페이지네이션 필드를 읽으세요
조회 응답에는 data, pagination, credits가 들어 있습니다. data의 레코드는 상위 시스템의 평면 원본 객체이며, 필요한 제목, 작성자, 날짜, permalink가 없을 수 있습니다. 아카이브는 _doc 순서를 사용하며 시간순, 관련도순, 점수순이 아닙니다. 앱에서 조회한 일부를 정렬할 수는 있지만, 그 일부가 전체 아카이브에서 가장 최신이거나 가장 높은 순위라고 만들 수는 없습니다.
pagination.page를 증가시킬 때 필터와 limit을 유지하세요. pagination.has_more는 가능한 경우 미리 읽은 추가 레코드를 이용합니다. false이면 자동으로 다음 요청을 보내는 동작을 제공하지 마세요. pagination.window_exhausted는 제한된 마지막 페이지 조건을 나타냅니다. 여기에 도달해도 일치하는 아카이브 자료를 모두 조회했다는 증거는 아닙니다.
레코드 수와 페이지의 범위는 각각 1–100입니다. pagination.total은 pagination.relation과 함께 읽어야 합니다. eq는 해당 응답의 집계 의미에서 정확한 수, gte는 하한, unknown은 신뢰할 총수가 없음을 뜻하며 null일 수도 있습니다. 첫 페이지 이후의 빈 페이지로는 총수를 확정할 수 없습니다. limit=100인 꽉 찬 100페이지에는 추가 선행 조회 여유가 없어 총수는 하한값이며, 페이지 상한에서는 has_more가 false입니다. subreddit 집계의 total은 알 수 없는 값이고, pagination.truncated는 집계에서 빠진 버킷이 있음을 나타냅니다.
과금과 실패를 명확히 처리하세요
정상적으로 완료된 조회는 빈 data 배열을 반환해도 1크레딧을 사용합니다. 보내기 전에 입력을 검증하고, 로딩 표시를 움직이기 위해 페이지를 조회하지 마세요. HTTP 400은 잘못된 입력, 401은 누락되거나 유효하지 않은 서비스 키, 402는 크레딧 부족, 429는 요청 속도 제한을 뜻합니다. 이런 거부된 요청에는 조회 크레딧을 예약하지 않습니다.
상위 시스템 요청 실패는 HTTP 502로 반환되며, 예약한 크레딧을 반환하거나 반환 대사 처리가 보류 중임을 알립니다. 앱과 통신하는 경계에서 응답을 잃으면 결과는 불확실하므로 무료였다고 가정하지 마세요. 쿼리 상태를 유지하고 Retry-After를 지키며, 적절한 경우 사용자가 재시도를 선택하게 하세요. 인증 정보와 잔액 관리는 하이킹 앱 사용자가 아니라 운영자의 일입니다.
응답을 정확한 읽기 화면으로 바꾸세요
레코드의 텍스트를 표시하기 전에 이스케이프 처리하세요. 출처 식별 정보와 출처 링크가 있으면 보존하고, 날짜가 없으면 알 수 없다고 표시하며, 레코드 작성 시각과 앱의 조회 시각을 구분합니다. 상위·연결 식별자가 있으면 로컬에서 묶을 수 있지만, 누락된 조상 레코드를 제공하는 것은 아닙니다.
「화면 상태」는 제안하는 로딩, 빈 결과, 실패 메시지를 다룹니다. 「앱 사용 흐름」의 구현 노트에서는 카드, 기기에 저장하는 참조 정보, 요청 예산을 설명합니다. 「키와 크레딧」에는 계정 준비와 요금이 함께 있습니다. 자체 구현을 검토하고 테스트하세요. 이 예시가 실시간으로 작동하는 기능이나 현재 등산로에 관한 조언을 입증하지는 않습니다.
