246 lines
6.9 KiB
Markdown
246 lines
6.9 KiB
Markdown
# 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 - 특정 미리 정의된 서비스 조회
|
|
```
|
|
|
|
## 요청/응답 형식
|
|
|
|
### 성공 응답 형식
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": { ... },
|
|
"message": "성공 메시지"
|
|
}
|
|
```
|
|
|
|
### 에러 응답 형식
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": {
|
|
"code": "ERROR_CODE",
|
|
"message": "에러 메시지",
|
|
"details": { ... }
|
|
}
|
|
}
|
|
```
|
|
|
|
## 주요 데이터 모델 (API 요청/응답용)
|
|
|
|
### 구독 (Subscription)
|
|
```json
|
|
{
|
|
"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)
|
|
```json
|
|
{
|
|
"id": "uuid-string",
|
|
"name": "카테고리 이름",
|
|
"icon": "icon_code",
|
|
"color": "#FF006E",
|
|
"createdAt": "2023-01-01T00:00:00Z",
|
|
"updatedAt": "2023-01-01T00:00:00Z"
|
|
}
|
|
```
|
|
|
|
### 결제 내역 (Payment)
|
|
```json
|
|
{
|
|
"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)
|
|
```json
|
|
{
|
|
"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
|
|
```
|
|
|
|
### 응답 형식
|
|
```json
|
|
{
|
|
"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 연동 (구독 서비스 제공업체)
|