6.9 KiB
6.9 KiB
Subscription Manager - API 설계
개요
이 문서는 Subscription Manager 앱의 API 설계를 정의합니다. 초기 MVP에서는 로컬 데이터베이스만 사용하지만, 향후 클라우드 동기화 및 외부 서비스 연동을 위한 API 설계를 미리 준비합니다.
API 설계 원칙
- RESTful 원칙 준수: 자원 중심 설계, HTTP 메소드 활용
- JSON 포맷: 모든 요청/응답은 JSON 형식 사용
- 버전 관리: API 경로에 버전 정보 포함 (예: /api/v1/...)
- 인증 필수: 모든 API 요청은 인증 필요 (JWT 토큰 기반)
- 에러 처리 표준화: 일관된 에러 응답 형식 제공
인증 및 보안
- 인증 방식: JWT (JSON Web Token)
- 토큰 갱신: Refresh Token 메커니즘 활용
- HTTPS 필수: 모든 API 통신은 HTTPS로 암호화
- Rate Limiting: 과도한 요청 방지를 위한 제한 적용
API 엔드포인트
사용자 관리
POST /api/v1/auth/register - 사용자 등록
POST /api/v1/auth/login - 로그인
POST /api/v1/auth/refresh - 토큰 갱신
POST /api/v1/auth/logout - 로그아웃
GET /api/v1/users/me - 현재 사용자 정보 조회
PUT /api/v1/users/me - 사용자 정보 업데이트
구독 관리
GET /api/v1/subscriptions - 구독 목록 조회
POST /api/v1/subscriptions - 새 구독 추가
GET /api/v1/subscriptions/:id - 특정 구독 조회
PUT /api/v1/subscriptions/:id - 구독 정보 업데이트
DELETE /api/v1/subscriptions/:id - 구독 삭제
카테고리 관리
GET /api/v1/categories - 카테고리 목록 조회
POST /api/v1/categories - 새 카테고리 추가
GET /api/v1/categories/:id - 특정 카테고리 조회
PUT /api/v1/categories/:id - 카테고리 정보 업데이트
DELETE /api/v1/categories/:id - 카테고리 삭제
결제 내역
GET /api/v1/payments - 결제 내역 목록 조회
POST /api/v1/payments - 새 결제 내역 추가
GET /api/v1/payments/:id - 특정 결제 내역 조회
PUT /api/v1/payments/:id - 결제 내역 업데이트
DELETE /api/v1/payments/:id - 결제 내역 삭제
GET /api/v1/subscriptions/:id/payments - 특정 구독의 결제 내역 조회
사용량 관리
GET /api/v1/usages - 사용량 목록 조회
POST /api/v1/usages - 새 사용량 기록 추가
GET /api/v1/usages/:id - 특정 사용량 기록 조회
PUT /api/v1/usages/:id - 사용량 기록 업데이트
DELETE /api/v1/usages/:id - 사용량 기록 삭제
GET /api/v1/subscriptions/:id/usages - 특정 구독의 사용량 기록 조회
분석 및 통계
GET /api/v1/analytics/monthly - 월별 비용 분석
GET /api/v1/analytics/category - 카테고리별 비용 분석
GET /api/v1/analytics/trend - 비용 추이 분석
GET /api/v1/analytics/summary - 요약 통계
설정 및 환경설정
GET /api/v1/settings - 설정 조회
PUT /api/v1/settings - 설정 업데이트
데이터 동기화
POST /api/v1/sync - 데이터 동기화 요청
GET /api/v1/sync/status - 동기화 상태 확인
미리 정의된 서비스
GET /api/v1/predefined-services - 미리 정의된 서비스 목록 조회
GET /api/v1/predefined-services/:id - 특정 미리 정의된 서비스 조회
요청/응답 형식
성공 응답 형식
{
"success": true,
"data": { ... },
"message": "성공 메시지"
}
에러 응답 형식
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "에러 메시지",
"details": { ... }
}
}
주요 데이터 모델 (API 요청/응답용)
구독 (Subscription)
{
"id": "uuid-string",
"name": "서비스 이름",
"description": "서비스 설명",
"amount": 9.99,
"currency": "USD",
"billingCycle": "monthly",
"cycleDays": null,
"startDate": "2023-01-01T00:00:00Z",
"nextBillingDate": "2023-02-01T00:00:00Z",
"categoryId": "category-uuid",
"logoPath": "path/to/logo.png",
"color": "#3A86FF",
"reminderDays": 3,
"notes": "사용자 메모",
"isActive": true,
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z"
}
카테고리 (Category)
{
"id": "uuid-string",
"name": "카테고리 이름",
"icon": "icon_code",
"color": "#FF006E",
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z"
}
결제 내역 (Payment)
{
"id": "uuid-string",
"subscriptionId": "subscription-uuid",
"amount": 9.99,
"currency": "USD",
"paymentDate": "2023-01-01T00:00:00Z",
"status": "paid",
"notes": "메모",
"createdAt": "2023-01-01T00:00:00Z"
}
사용량 (Usage)
{
"id": "uuid-string",
"subscriptionId": "subscription-uuid",
"date": "2023-01-01T00:00:00Z",
"amount": 100,
"unit": "API 호출",
"notes": "메모",
"createdAt": "2023-01-01T00:00:00Z"
}
페이지네이션
목록 조회 API는 페이지네이션을 지원합니다.
요청 파라미터
GET /api/v1/subscriptions?page=1&limit=10&sort=name&order=asc
응답 형식
{
"success": true,
"data": {
"items": [ ... ],
"pagination": {
"total": 100,
"page": 1,
"limit": 10,
"pages": 10
}
}
}
필터링 및 검색
목록 조회 API는 필터링 및 검색을 지원합니다.
요청 파라미터
GET /api/v1/subscriptions?search=netflix&category=entertainment&minAmount=5&maxAmount=15
API 버전 관리
API 변경 시 하위 호환성을 유지하기 위해 버전 관리를 적용합니다.
- 메이저 변경: 새 버전 경로 사용 (예: /api/v2/...)
- 마이너 변경: 기존 버전 유지하면서 기능 추가
에러 코드
AUTH_001: 인증 실패AUTH_002: 토큰 만료AUTH_003: 권한 없음VALIDATION_001: 유효성 검사 실패RESOURCE_001: 리소스 찾을 수 없음SERVER_001: 서버 내부 오류
API 사용량 제한
- 기본 제한: 분당 60 요청
- 프리미엄 사용자: 분당 300 요청
API 문서화
- Swagger/OpenAPI 스펙을 사용한 API 문서 자동화
- 각 엔드포인트에 대한 상세 설명, 파라미터, 응답 예시 제공
클라이언트 구현 가이드
- HTTP 클라이언트: Dio 패키지 사용
- 인증 토큰 관리: 안전한 저장소에 JWT 토큰 저장
- 오프라인 지원: 요청 큐잉 및 자동 재시도 구현
- 에러 처리: 표준화된 에러 핸들링 적용
향후 확장 계획
- GraphQL API 추가 지원
- 웹훅 기능 추가
- 실시간 알림을 위한 WebSocket 지원
- 서드파티 API 연동 (구독 서비스 제공업체)