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

사용자 프로필 조회 API

개요​

사용자 프로필 조회 API는 사용자의 개인화 설정 정보를 제공합니다. 이 API를 통해 사용자의 이름, 언어 설정, 타임존 정보 등의 프로필 데이터를 조회할 수 있습니다.

주요 기능​

  • 사용자 정보: 사용자 ID, 이름 등 기본 정보
  • 언어 설정: 사용자가 설정한 언어 (ko-KR, en-US, de-DE 등)
  • 타임존 정보: 타임존 ID와 UTC 기준 오프셋 (분 단위)
  • 메타데이터: 프로필 생성 및 업데이트 시간

날짜 형식 규칙​

이 API는 Unix Timestamp (13자리) 형식을 사용합니다:

  • Unix Timestamp (13자리): 정확한 시간 정보
    • createdAt: 프로필 생성 시간
    • updatedAt: 프로필 마지막 업데이트 시간

현재 사용자 프로필 조회​

현재 로그인한 사용자 자신의 프로필 정보를 조회합니다.

  • HTTP Method: GET
  • Path: /v1/users/me/profile
  • 인증: 액세스 토큰 (accessToken) 필요

Headers​

HeaderTypeDescriptionRequired
AuthorizationBearer {accessToken}사용자 인증을 통해 발급받은 액세스 토큰입니다.Yes

Request Body​

이 API는 GET 요청이므로 요청 본문이 없습니다. 모든 필요한 정보는 JWT 토큰을 통해 전달됩니다.

Responses​

HTTP Status Code설명Error Code(s)
200 OK성공-
401 Unauthorized인증 실패 (토큰 누락, 만료, 유효하지 않음)-
404 Not Found사용자 또는 프로필을 찾을 수 없음7002, 7006
500 Internal Server Error서버 내부 오류7000
200 OK - 성공

프로필 조회 성공:

{
  "userId": "user_123",
  "userName": "홍길동",
  "language": "ko-KR",
  "timezoneId": "Asia/Seoul",
  "offsetInMinutes": 540,
  "createdAt": 1711929600000,
  "updatedAt": 1714523700000
}
필드타입설명
userIdstring사용자 ID
userNamestring사용자 이름 (선택적, null 가능)
languagestring사용자 언어 설정 (예: "ko-KR", "en-US", "de-DE")
timezoneIdstring타임존 ID (예: "Asia/Seoul", "Europe/Berlin", "America/New_York")
offsetInMinutesnumberUTC 기준 오프셋 (분 단위, Kotlin: Int, Swift: Int, 예: 540 = UTC+9)
createdAtnumber프로필 생성 시간 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)
updatedAtnumber프로필 마지막 업데이트 시간 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)
401 Unauthorized - 인증 실패

예시: 토큰이 누락된 경우

{
  "message": "Unauthorized",
  "statusCode": 401
}
404 Not Found - 사용자를 찾을 수 없음

예시: 사용자 없음 (USER_NOT_FOUND - 7002)

{
  "code": 7002,
  "message": "USER_NOT_FOUND",
  "detail": "사용자를 찾을 수 없습니다.",
  "metadata": {
    "userId": "user_123"
  }
}

예시: 프로필 없음 (USER_PROFILE_NOT_FOUND - 7006)

{
  "code": 7006,
  "message": "USER_PROFILE_NOT_FOUND",
  "detail": "사용자 프로필을 찾을 수 없습니다.",
  "metadata": {
    "userId": "user_123"
  }
}
500 Internal Server Error - 서버 내부 오류

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

{
  "code": 7000,
  "message": "SERVER_ERROR",
  "detail": "사용자 서비스 처리 중 서버 오류가 발생했습니다."
}

관리자용 사용자 프로필 조회​

관리자가 특정 사용자의 프로필 정보를 조회합니다.

  • HTTP Method: GET
  • Path: /v1/users/{userId}/profile
  • 인증: 관리자 액세스 토큰 (adminToken) 필요

Path Parameters​

ParameterTypeDescriptionRequired
userIdstring조회할 사용자의 ID (UUID 형식)Yes

Headers​

HeaderTypeDescriptionRequired
AuthorizationBearer {adminToken}관리자 인증을 통해 발급받은 액세스 토큰입니다.Yes

Request Body​

이 API는 GET 요청이므로 요청 본문이 없습니다.

Responses​

HTTP Status Code설명Error Code(s)
200 OK성공-
400 Bad Request잘못된 요청 (userId 형식 오류)-
401 Unauthorized인증 실패 (토큰 누락, 만료, 유효하지 않음)-
403 Forbidden권한 없음 (관리자 권한 필요)2060
404 Not Found사용자 또는 프로필을 찾을 수 없음7002, 7006
500 Internal Server Error서버 내부 오류7000
200 OK - 성공

관리자용 프로필 조회 성공:

{
  "userId": "user_456",
  "userName": "김철수",
  "language": "de-DE",
  "timezoneId": "Europe/Berlin",
  "offsetInMinutes": 60,
  "createdAt": 1711929600000,
  "updatedAt": 1714523700000
}

응답 필드는 현재 사용자 프로필 조회와 동일합니다.

400 Bad Request - 잘못된 요청

예시: UUID 형식 오류

{
  "message": "Validation failed (uuid is expected)",
  "error": "Bad Request",
  "statusCode": 400
}
403 Forbidden - 권한 없음

예시: 관리자 권한 부족 (PERMISSION_DENIED - 2060)

{
  "code": 2060,
  "message": "PERMISSION_DENIED",
  "detail": "다른 사용자의 프로필을 조회할 권한이 없습니다."
}
404 Not Found - 사용자를 찾을 수 없음

예시: 사용자 없음 (USER_NOT_FOUND - 7002)

{
  "code": 7002,
  "message": "USER_NOT_FOUND",
  "detail": "사용자를 찾을 수 없습니다.",
  "metadata": {
    "userId": "user_456"
  }
}

예시: 프로필 없음 (USER_PROFILE_NOT_FOUND - 7006)

{
  "code": 7006,
  "message": "USER_PROFILE_NOT_FOUND",
  "detail": "사용자 프로필을 찾을 수 없습니다.",
  "metadata": {
    "userId": "user_456"
  }
}
500 Internal Server Error - 서버 내부 오류

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

{
  "code": 7000,
  "message": "SERVER_ERROR",
  "detail": "사용자 서비스 처리 중 서버 오류가 발생했습니다."
}

사용 예시​

현재 사용자 프로필 조회​

curl -X GET "https://api.example.com/v1/users/me/profile" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

관리자용 특정 사용자 프로필 조회​

curl -X GET "https://api.example.com/v1/users/user_456/profile" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json"

참고사항​

  • 타임존 정보: timezoneId는 IANA Time Zone Database의 표준 타임존 식별자를 사용합니다.
  • 오프셋 계산: offsetInMinutes는 UTC 기준으로 계산됩니다. 양수는 UTC보다 빠른 시간, 음수는 늦은 시간을 의미합니다.
  • 사용자 이름: userName은 선택적 필드로, 설정되지 않은 경우 null이 될 수 있습니다.
  • 캐싱: 프로필 정보는 성능 최적화를 위해 캐싱될 수 있습니다.