번개라디오 개발자 가이드

로컬에서 개발하는 번개라디오 앱을 위한 백엔드 API 명세입니다. (AI 코더 참고용)

Base URL

https://tune.tideflo.work/api/v1

모든 응답은 application/json; charset=utf-8 입니다. CORS는 허용되어 있습니다.

표준 응답 형식

성공:

{
  "success": true,
  "data": { ... },
  "meta": { "page": 1, "per_page": 30, "total": 37, "total_pages": 2 }
}

• data — 실제 페이로드 (객체 또는 배열)
• meta — 목록 응답에만 포함(페이지네이션)

실패:

{
  "success": false,
  "error": { "code": "not_found", "message": "채널을 찾을 수 없습니다" }
}

HTTP 상태코드도 함께 사용합니다(200/201/400/401/404/409/422/502 등). 자세한 내용은 에러 코드 참고.

인증 개요

• 익명 청취: 방송국 목록·상세·스트림 재생은 인증 없이 호출 가능합니다. (기존 번개라디오 UX 유지)
• 선택적 계정: 즐겨찾기 동기화 등은 이메일+비밀번호 계정으로 발급받은 Bearer 토큰 사용.
• 기기 식별: 계정 없이도 X-Device-UUID 헤더로 기기 단위 즐겨찾기가 가능합니다.
• 2차 계획: 구글/카카오/네이버 소셜 로그인.

자세한 내용은 계정·즐겨찾기 참고.

빠른 시작

# 헬스체크
curl https://tune.tideflo.work/api/v1/health

# 추천 방송국 목록
curl "https://tune.tideflo.work/api/v1/stations?featured=1"

# 특정 채널 재생 URL 발급 (KBS 쿨FM 예)
curl https://tune.tideflo.work/api/v1/stations/kbs-coolfm
curl https://tune.tideflo.work/api/v1/stations/5/stream

엔드포인트 요약