API 개요¶
Hipster Timer Backend는 세 가지 유형의 API를 제공합니다:
- REST API - 전통적인 HTTP 엔드포인트
- GraphQL API - 유연한 쿼리 언어
- WebSocket API - 실시간 통신
기본 URL¶
모든 API는 /v1 접두사로 제공됩니다:
- 개발:
http://localhost:2614/v1 - 프로덕션:
https://your-domain.com/v1
인증¶
모든 API 엔드포인트(헬스체크 제외)는 OIDC Bearer 토큰 인증이 필요합니다:
📖 상세 가이드: 인증 가이드
API 유형¶
REST API¶
CRUD 작업을 위한 전통적인 RESTful 엔드포인트:
- 일정:
/v1/schedules - 타이머:
/v1/timers - 투두:
/v1/todos - 태그:
/v1/tags - 공휴일:
/v1/holidays
📖 상세 가이드: REST API 레퍼런스
GraphQL API¶
효율적인 데이터 조회를 위한 유연한 쿼리 언어:
- 엔드포인트:
/v1/graphql - 플레이그라운드:
/v1/graphql(개발 환경만)
📖 상세 가이드: GraphQL 가이드
WebSocket API¶
타이머 제어를 위한 실시간 통신:
- 엔드포인트:
/v1/ws/timers - 프로토콜: JSON 메시지를 사용하는 WebSocket
📖 상세 가이드: WebSocket 가이드
Rate Limiting¶
모든 API는 Rate Limiting이 적용됩니다:
- 기본값: 사용자당 60초에 60회 요청
- 헤더:
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset
📖 상세 가이드: Rate Limiting 가이드
에러 처리¶
모든 API는 일관된 에러 응답을 반환합니다:
일반적인 HTTP 상태 코드:
200- 성공201- 생성됨400- 잘못된 요청401- 인증 필요403- 권한 없음404- 찾을 수 없음429- 요청 한도 초과500- 서버 내부 오류
데이터 형식¶
- 요청: JSON (
Content-Type: application/json) - 응답: JSON (
Content-Type: application/json) - 날짜: ISO 8601 형식 (
2024-01-15T10:00:00Z) - UUID: 표준 UUID v4 형식
대화형 문서 (테스트 링크)¶
로컬 개발 서버 실행 시 아래 주소로 접속해 API를 테스트할 수 있습니다.
| 항목 | 테스트 링크 (Development) |
|---|---|
| Swagger UI | http://localhost:2614/docs |
| ReDoc | http://localhost:2614/redoc |
| GraphQL Playground | http://localhost:2614/v1/graphql |
| WebSocket Playground | http://localhost:2614/ws-playground |
| WebSocket (타이머 엔드포인트) | ws://localhost:2614/v1/ws/timers |
주의
위 링크는 개발 모드(DOCS_ENABLED=true)에서만 제공됩니다. WebSocket Playground는 JWT 입력 후 브라우저에서 바로 타이머 WebSocket API를 테스트할 수 있는 자체 제공 페이지입니다.