최신 이완요법 콘텐츠 번들 조회 API
최신 이완요법 콘텐츠 번들 조회 API는 가장 최신 버전의 이완요법 콘텐츠 번들 정보를 조회하는 기능을 제공합니다. 번들에는 이완요법 카테고리와 콘텐츠가 포함되며, 언어별 번역 데이터와 함께 제공됩니다.
최신 번들 조회
가장 최신 버전의 이완요법 콘텐츠 번들을 자동으로 조회하여 설정된 언어에 따라 번역된 데이터를 반환합니다. 번들은 사용자의 캐싱 최적화를 위해 설계되어 있으며, 앱은 번들 ID 기반으로 콘텐츠를 효율적으로 관리할 수 있습니다.
- HTTP Method:
GET - Path:
/v1/relaxation/bundles/latest - 인증: App Token 필요 (Authorization: Bearer
{appToken})
Headers
| Header | Type | Description | Required |
|---|---|---|---|
Authorization | Bearer {appToken} | App 토큰을 통한 인증 | Yes |
Accept-Language | string | 응답 언어 지정 (Language Code 참조, 예: de-DE, en-US, ko-KR) | Yes |
Responses
| HTTP Status Code | 설명 | Error Code(s) |
|---|---|---|
200 OK | 번들 조회 성공 | - |
401 Unauthorized | 인증되지 않음 | 2051 |
404 Not Found | 활성 번들 없음 | 13031 |
404 Not Found | 번들 콘텐츠 없음 | 13030 |
500 Internal Server Error | 서버 내부 오류 | 13000 |
200 OK - 번들 조회 성공
성공적으로 최신 번들을 조회하면 RelaxationBundleResponseDto에 정의된 번들 정보가 반환됩니다. 여기에는 번들 ID, 버전, 언어 설정, 그리고 번들에 포함된 카테고리와 콘텐츠 목록이 포함됩니다.
최신 번들 응답 예시
{
"bundleId": "bundle_v1_2_0",
"language": "ko-KR",
"categories": [
{
"id": "ce06c647-42ab-4905-93ba-4921fd6d594f",
"orderIndex": 0,
"title": "호흡요법",
"summary": "호흡을 통한 이완 기법"
},
{
"id": "e11177d4-ce72-4bd5-b7ac-24eafa376752",
"orderIndex": 1,
"title": "점진적 근육이완",
"summary": "근육의 긴장과 이완을 통한 이완법"
},
{
"id": "8f2d5b3a-9c1e-4d7a-b5f3-6e9a2c8d1f4b",
"orderIndex": 2,
"title": "아우토겐 트레이닝",
"summary": "자율훈련법을 통한 깊은 이완"
},
{
"id": "7a4f8c2e-5b9d-4c3a-8f1e-9b6d2a5c7e8f",
"orderIndex": 3,
"title": "상상하기",
"summary": "시각화를 통한 심리적 이완"
},
{
"id": "e11177d4-ce72-4bd5-b7ac-24eafa376752",
"orderIndex": 4,
"title": "마음챙김",
"summary": "현재 순간에 집중하는 명상법"
}
],
"contents": [
{
"id": "3a8d797d-dd65-438e-a257-5b150933da70",
"categoryId": "e11177d4-ce72-4bd5-b7ac-24eafa376752",
"thumbnailImageUrl": "https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/thumbnails/content_25.jpg",
"lottieFileUrl": "https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/lottie_files/content_25.json",
"backgroundLottieUrl": "https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/background_lottie.json",
"backgroundImageUrl": "https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/background_image.jpg",
"audioFileUrl": "https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/audio_files/content_25.mp3",
"durationSeconds": 1020,
"orderIndex": 4,
"level": "DIFFICULT",
"stress": "HIGH",
"poses": ["LYING_DOWN", "SITTING"],
"title": "걷기 명상",
"summary": "걷기 명상은 부드러운 움직임과 의식적인 마음챙김을 결합합니다. 가만히 앉는 대신 각 걸음에 주의를 집중합니다."
},
{
"id": "da2df843-85bf-4670-93e9-e4629ff5ddb4",
"categoryId": "ce06c647-42ab-4905-93ba-4921fd6d594f",
"thumbnailImageUrl": "https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_02/thumbnails/content_11.jpg",
"lottieFileUrl": "https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_02/lottie_files/content_11.json",
"backgroundLottieUrl": "https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_02/background_lottie.json",
"audioFileUrl": "https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_02/audio_files/content_11.mp3",
"durationSeconds": 720,
"orderIndex": 5,
"level": "DIFFICULT",
"stress": "HIGH",
"poses": ["LYING_DOWN", "SITTING"],
"title": "간소화 버전(숙련 후)",
"summary": "이 연습은 전신을 포함하며 이미 점진적 근육이완법에 대한 경험을 쌓은 경우에 특히 적합합니다."
},
{
"id": "48052a17-fb61-4e5d-bf8b-0852e05d6bfb",
"categoryId": "e11177d4-ce72-4bd5-b7ac-24eafa376752",
"thumbnailImageUrl": "https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/thumbnails/content_26.jpg",
"lottieFileUrl": "https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/lottie_files/content_26.json",
"backgroundImageUrl": "https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/background_image_alt.jpg",
"audioFileUrl": "https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/audio_files/content_26.mp3",
"durationSeconds": 1080,
"orderIndex": 5,
"level": "DIFFICULT",
"stress": "HIGH",
"poses": ["LYING_DOWN", "SITTING"],
"title": "상황별 걷기 명상",
"summary": "이 연습은 다양한 시나리오를 통해 걸으면서 걸음걸이와 자세의 변화를 의식적으로 인식함으로써 움직임과 마음챙김을 결합합니다. 몸의 인식과 내적 상태에 대한 감각을 개발하는 데 도움이 됩니다."
}
]
}
RelaxationBundleResponseDto 필드 설명
| 필드 | 타입 | 설명 | 예시 | 필수 (Yes/No) |
|---|---|---|---|---|
bundleId | string | 번들 ID | bundle_v1_2_0 | Yes |
language | string | 응답 언어 (Language Code 참조) | ko-KR | Yes |
categories | RelaxationCategoryDto[] | 카테고리 정보 배열 | (아래 상세 참조) | No |
contents | RelaxationContentDto[] | 콘텐츠 정보 배열 | (아래 상세 참조) | No |
RelaxationCategoryDto 필드 설명
| 필드 | 타입 | 설명 | 예시 | 필수 (Yes/No) |
|---|---|---|---|---|
id | string | 카테고리 ID | cat_breathing | Yes |
orderIndex | integer | 정렬 순서 | 0 | Yes |
title | string | 카테고리 제목 | 호흡요법 | Yes |
summary | string | 카테고리 요약 | 호흡을 통한 이완 기법 | Yes |
RelaxationContentDto 필드 설명
| 필드 | 타입 | 설명 | 예시 | 필수 (Yes/No) |
|---|---|---|---|---|
id | string | 콘텐츠 ID (UUID 형식) | 3a8d797d-dd65-438e-a257-5b150933da70 | Yes |
categoryId | string | 카테고리 ID (UUID 형식) | e11177d4-ce72-4bd5-b7ac-24eafa376752 | Yes |
thumbnailImageUrl | string | 썸네일 이미지 URL | https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/thumbnails/content_25.jpg | Yes |
lottieFileUrl | string | Lottie 애니메이션 파일 URL | https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/lottie_files/content_25.json | Yes |
backgroundLottieUrl | string | 배경 Lottie 애니메이션 URL (선택사항) | https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/background_lottie.json | No |
backgroundImageUrl | string | 배경 이미지 URL (선택사항) | https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/background_image.jpg | No |
audioFileUrl | string | 오디오 파일 URL | https://storage.googleapis.com/dta-wide/dev/relaxation/media/ko-KR/1.0.0/category_05/audio_files/content_25.mp3 | Yes |
durationSeconds | integer | 재생 시간 (초) | 1020 | Yes |
orderIndex | integer | 카테고리 내 정렬 순서 | 4 | Yes |
level | string | 난이도 (Relaxation Level 참조) | DIFFICULT | Yes |
stress | string | 스트레스 수준 (Relaxation Stress 참조) | HIGH | Yes |
poses | string[] | 권장 자세 배열 (Relaxation Pose 참조) | ["LYING_DOWN", "SITTING"] | Yes |
title | string | 콘텐츠 제목 | 걷기 명상 | Yes |
summary | string | 콘텐츠 설명 | 걷기 명상은 부드러운 움직임과 의식적인 마음챙김을 결합합니다. 가만히 앉는 대신 각 걸음에 주의를 집중합니다. | Yes |
401 Unauthorized - 인증되지 않음
유효하지 않은 앱 토큰이 제공되었거나 토큰이 만료된 경우 반환됩니다.
{
"code": 2051,
"message": "INVALID_TOKEN",
"detail": "토큰이 유효하지 않습니다"
}
404 Not Found - 활성 번들 없음
현재 활성화된 이완요법 번들이 존재하지 않는 경우 반환됩니다.
{
"code": 13031,
"message": "NO_ACTIVE_BUNDLE",
"detail": "현재 활성화된 이완요법 번들이 없습니다"
}
404 Not Found - 번들 콘텐츠 없음
활성 번들의 콘텐츠를 찾을 수 없는 경우 반환됩니다.
{
"code": 13030,
"message": "BUNDLE_NOT_FOUND",
"detail": "번들 콘텐츠를 찾을 수 없습니다"
}
500 Internal Server Error - 서버 내부 오류
데이터베이스 연결 실패 등 서버 내부 오류가 발생한 경우 반환됩니다.
{
"code": 13000,
"message": "SERVER_ERROR",
"detail": "서버 내부 오류가 발생했습니다"
}
데이터베이스 접근 오류 (13500)
{
"code": 13500,
"message": "REPOSITORY_ERROR",
"detail": "데이터베이스 연결 및 처리 오류"
}
주요 특징
자동 최신 번들 선택
- 현재 활성 상태인 가장 최신 버전의 번들을 자동으로 선택합니다
- 별도의 번들 ID를 지정할 필요가 없어 클라이언트 구현이 간소화됩니다
- 새로운 번들이 배포되면 자동으로 최신 버전으로 응답됩니다
고정 옵션
- 이완요법 콘텐츠의 일관성을 위해 다음 옵션들이 고정적으로 적용됩니다:
includeContents = true: 항상 콘텐츠 정보 포함includeCategories = true: 항상 카테고리 정보 포함
다국어 지원
Accept-Language헤더를 통해 원하는 언어로 번역된 콘텐츠를 받을 수 있습니다- 지원 언어: 독일어(de-DE), 한국어(ko-KR), 영어(en-US)
- 요청한 언어의 번역이 없는 경우 기본 언어(독일어)로 대체됩니다
응답 구조
- bundleId: 현재 활성 번들의 고유 식별자
- language: 요청된 응답 언어
- categories: 이완요법 카테고리 목록
- title: 카테고리 제목
- summary: 카테고리 요약
- orderIndex: 카테고리 표시 순서
- contents: 이완요법 콘텐츠 목록
- level: 난이도 (초급, 중급, 고급)
- stress: 스트레스 수준 (낮음, 보통, 높음)
- poses: 권장 자세 (누워서, 앉아서, 서서)
- durationSeconds: 재생 시간 (초 단위)
- audioFileUrl: 오디오 가이드 파일 URL
- lottieFileUrl: 애니메이션 가이드 파일 URL
- backgroundLottieUrl: 배경 Lottie 애니메이션 URL (선택사항)
- backgroundImageUrl: 배경 이미지 URL (선택사항)
- metadata: 번들 메타데이터 (콘텐츠 수, 총 용량)
캐싱 고려사항
- 클라이언트는
bundleId를 기준으로 응답을 캐싱할 수 있습니다 - 번들 버전이 업데이트되면 새로운
bundleId가 생성되므로 캐시 무효화가 자동으로 처리됩니다 - 동일한
bundleId에 대해서는 안전하게 캐시된 데이터를 사용할 수 있습니다
최적화 기능
- Redis 캐시를 활용한 고성능 조회 (1-3ms 응답 시간)
- 번들 유효성 검증 포함
- 언어별 번역 데이터 자동 포함
- 미디어 파일 URL 사전 서명 포함
에러 응답
발생 가능한 에러들
| HTTP 상태 코드 | 에러 코드 | 에러 메시지 | 설명 |
|---|---|---|---|
| 401 | INVALID_TOKEN (2051) | 토큰이 유효하지 않습니다 | 인증 토큰이 없거나 유효하지 않을 때 |
| 404 | NO_ACTIVE_BUNDLE (13031) | 현재 활성화된 이완요법 번들이 없습니다 | 활성화된 번들이 존재하지 않을 때 |
| 404 | BUNDLE_NOT_FOUND (13030) | 번들 콘텐츠를 찾을 수 없습니다 | 활성 번들의 콘텐츠를 찾을 수 없을 때 |
| 500 | SERVER_ERROR (13000) | 서버 내부 오류가 발생했습니다 | 예상치 못한 서버 오류가 발생했을 때 |
| 500 | REPOSITORY_ERROR (13500) | 데이터베이스 연결 및 처리 오류 | 데이터베이스 접근 중 오류가 발생했을 때 |
에러 응답 예시
401 Unauthorized - 인증 실패
{
"code": 2051,
"message": "INVALID_TOKEN",
"detail": "토큰이 유효하지 않습니다"
}
404 Not Found - 활성 번들 없음
{
"code": 13031,
"message": "NO_ACTIVE_BUNDLE",
"detail": "현재 활성화된 이완요법 번들이 없습니다"
}
404 Not Found - 번들 콘텐츠 없음
{
"code": 13030,
"message": "BUNDLE_NOT_FOUND",
"detail": "번들 콘텐츠를 찾을 수 없습니다"
}
500 Internal Server Error - 서버 오류
{
"code": 13000,
"message": "SERVER_ERROR",
"detail": "서버 내부 오류가 발생했습니다"
}
500 Internal Server Error - 데이터베이스 오류
{
"code": 13500,
"message": "REPOSITORY_ERROR",
"detail": "데이터베이스 연결 및 처리 오류"
}
성능 정보
- 평균 응답 시간: 1-5ms (캐시 활용 시)
- 최대 응답 시간: 800ms (캐시 미스 시)
- 캐시 TTL: 7일
- 캐시 적중률: 99% 이상 (예상)
변경 이력
| 버전 | 날짜 | 작성자 | 변경 내용 |
|---|---|---|---|
| 1.0.0 | 2025-07-15 | elizabeth@weltcorp.com | 최초 문서 작성 |
| 1.1.0 | 2025-07-16 | elizabeth@weltcorp.com | DTO 구조에 맞게 필드명 수정 (backgroundLottieUrl, durationSeconds) |
| 1.0.1 | 2025-07-17 | elizabeth@weltcorp.com | 실제 데이터 형식 반영: UUID ID, Google Storage URL, description→summary, metadata 제거, enum 값 업데이트 (DIFFICULT, LYING_DOWN) |
| 1.0.2 | 2025-07-17 | elizabeth@weltcorp.com | 에러 응답 간소화: INVALID_TOKEN 코드 2051로 수정, 불필요한 에러(400, 403, 404) 제거, 서버/레포지토리 에러만 유지 |
| 1.0.3 | 2025-07-17 | elizabeth@weltcorp.com | RelaxationCategoryDto에서 type 필드 제거, relaxation-category-type.md 참조 링크 제거 |
| 1.0.4 | 2025-07-18 | elizabeth@weltcorp.com | backgroundImageUrl 필드 추가, backgroundLottieUrl 및 backgroundImageUrl을 선택사항으로 변경 |