본문으로 건너뛰기
버전: 0.68.0

수면 목표 조회 API (일차 범위)

개요​

수면 목표 범위 조회 API는 사용자의 특정 일차 범위에 해당하는 수면 목표 데이터를 조회하는 기능을 제공합니다. 이 API는 캐시 우선 조회 방식을 사용하여 빠른 응답 속도를 보장하며, 수면 목표 추적과 달성률 분석의 기반 데이터를 제공합니다.

데이터 활용​

조회된 수면 목표는 다음과 같은 용도로 활용됩니다:

  • 목표 달성률 분석: 기간별 수면 목표 달성 현황 파악
  • 수면 패턴 개선: 목표 대비 실제 수면 패턴 비교 분석
  • 개인화된 목표 설정: 과거 목표 데이터 기반 최적 목표 수립
  • 차트 및 그래프: 수면 목표 데이터 시각화
  • rTIB 알고리즘: 수면 효율성 기반 목표 자동 조정

제약사항​

  • 존재하지 않는 일차 범위 조회 시 빈 배열 반환
  • 사용자는 자신의 수면 목표만 조회 가능
  • 시스템 생성 목표와 사용자 설정 목표 모두 조회 가능

수면 목표 범위 조회​

특정 일차 범위의 수면 목표를 조회합니다.

  • HTTP Method: GET
  • Path: /v1/sleep/goals/target-day-index-range
  • 인증: 액세스 토큰 (accessToken) 필요

Headers​

HeaderTypeDescriptionRequired
AuthorizationBearer {accessToken}사용자 인증을 통해 발급받은 액세스 토큰입니다.Yes
Accept-Languagede-DE, en-US, ko-KR오류 메시지의 언어를 지정합니다. 지역 코드를 포함한 형식(예: de-DE, en-US, ko-KR)만 지원합니다.No

Query Parameters​

ParameterTypeDescriptionRequired
startTargetDayIndexnumber조회할 시작 일차 (1부터 시작하는 정수값, Kotlin: Int, Swift: Int)Yes
endTargetDayIndexnumber조회할 종료 일차 (1부터 시작하는 정수값, Kotlin: Int, Swift: Int)Yes

Responses​

HTTP Status Code설명Error Code(s)
200 OK성공-
400 Bad Request잘못된 요청 (잘못된 파라미터)10002
403 Forbidden권한 없음 (다른 사용자의 데이터 접근 시도)10030
500 Internal Server Error서버 내부 오류10000
200 OK - 성공

수면 목표 범위 조회 성공:

{
  "items": [
    {
      "id": "sg_12345",
      "targetDayIndex": 7,
      "targetDate": "2024-05-10",
      "targetLOT": 1380,
      "targetAET": 1920,
      "rTIBMinutes": 540,
      "goalType": "RTIB_ALGORITHM",
      "createdAt": 1715311800000
    },
    {
      "id": "sg_12346",
      "targetDayIndex": 8,
      "targetDate": "2024-05-11",
      "targetLOT": 1380,
      "targetAET": 1920,
      "rTIBMinutes": 540,
      "goalType": "USER",
      "createdAt": 1715398200000
    },
    {
      "id": "sg_12347",
      "targetDayIndex": 9,
      "targetDate": "2024-05-12",
      "targetLOT": 1380,
      "targetAET": 1920,
      "rTIBMinutes": 540,
      "goalType": "SYSTEM",
      "createdAt": 1715484600000
    }
  ],
  "count": 3,
  "startTargetDayIndex": 7,
  "endTargetDayIndex": 9
}

빈 범위 조회 결과:

{
  "items": [],
  "count": 0,
  "startTargetDayIndex": 15,
  "endTargetDayIndex": 17
}
필드타입설명필수
itemsarray수면 목표 목록Yes
items[].idstring수면 목표 고유 IDYes
items[].targetDayIndexnumber치료 주기 일차 (Kotlin: Int, Swift: Int)Yes
items[].targetDatestring수면 목표 대상 날짜 (YYYY-MM-DD)Yes
items[].targetLOTnumber목표 취침 시각 (자정부터의 경과 분, Kotlin: Int, Swift: Int)Yes
items[].targetAETnumber목표 기상 시각 (자정부터의 경과 분, Kotlin: Int, Swift: Int)Yes
items[].rTIBMinutesnumber권장 침대 시간 (분, Kotlin: Int, Swift: Int)Yes
items[].goalTypestring목표 유형 (USER, RTIB_ALGORITHM, SYSTEM)Yes
items[].createdAtnumber생성 시각 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)Yes
countnumber조회된 수면 목표 총 개수 (Kotlin: Int, Swift: Int)Yes
startTargetDayIndexnumber요청한 시작 일차 (Kotlin: Int, Swift: Int)Yes
endTargetDayIndexnumber요청한 종료 일차 (Kotlin: Int, Swift: Int)Yes
400 Bad Request - 잘못된 요청

예시: 잘못된 파라미터 (INVALID_PARAMETERS - 10002)

{
  "code": 10002,
  "message": "INVALID_PARAMETERS",
  "detail": "시작 일차는 종료 일차보다 작거나 같아야 합니다.",
  "metadata": {
    "startTargetDayIndex": 10,
    "endTargetDayIndex": 5
  }
}
500 Internal Server Error - 서버 내부 오류

예시: 일반 서버 오류 (SERVER_ERROR - 10000)

{
  "code": 10000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류가 발생했습니다."
}

설명​

  • 이 API는 사용자의 특정 일차 범위 수면 목표를 조회하는 핵심 기능입니다.
  • 지능형 캐시 전략:
    • 7일 이하 범위: 개별 DayIndex 캐시를 조합하여 효율적 조회
    • 8일 이상 범위: 캐시를 우회하고 DB에서 직접 조회하여 성능 최적화
    • 부분 캐시 히트: 일부만 캐시에 있어도 활용하고, 누락된 부분만 DB에서 조회
    • 자동 캐시 저장: DB 조회 후 누락된 데이터만 선별하여 캐시에 저장
  • 데이터 형식:
    • targetLOT, targetAET: 자정부터의 경과 분
    • 목록 조회에 최적화된 핵심 필드만 포함
  • 수면 목표 유형별 응답:
    • rTIB 알고리즘 목표: 수면 효율성 기반 자동 계산된 목표 (RTIB_ALGORITHM)
    • 사용자 정의 목표: 사용자가 직접 설정한 목표 (USER)
    • 시스템 기본 목표: 시스템에서 제공하는 기본 목표 (SYSTEM)
  • 자동 계산 필드:
    • rTIBMinutes: 권장 침대 시간 = targetAET - targetLOT
  • 성능 최적화:
    • 소규모 범위(7일 이하)는 12시간 캐시로 빠른 응답
    • 대용량 범위는 캐시 우회로 메모리 효율성 확보
    • 캐시 실패 시에도 핵심 기능에 영향 없도록 설계
  • 데이터 활용:
    • 수면 목표 달성률 분석 및 개인화된 목표 설정
    • 기간별 수면 목표 추이 및 패턴 분석
    • 수면 목표 데이터 시각화 (차트, 그래프)
    • rTIB 알고리즘 기반 목표 자동 조정 시스템