본문으로 건너뛰기
버전: 개발 버전 (최신)

사용자 프로필 수정 API

개요​

사용자 프로필 수정 API는 사용자의 개인화 설정 정보를 업데이트할 수 있는 기능을 제공합니다. 이 API를 통해 사용자의 이름, 언어 설정, 타임존 정보 등의 프로필 데이터를 선택적으로 수정할 수 있습니다.

주요 기능​

  • 사용자 이름 수정: 사용자의 표시 이름 업데이트
  • 언어 설정 변경: 사용자 인터페이스 언어 설정 (ko-KR, de-DE, en-US)
  • 타임존 정보 수정: 타임존 ID 업데이트 (오프셋은 시스템에서 자동 관리)
  • 선택적 수정: 필요한 필드만 선택적으로 업데이트 가능

날짜 형식 규칙​

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

  • Unix Timestamp (13자리): 정확한 시간 정보
    • createdAt: 프로필 생성 시간 (수정되지 않음)
    • updatedAt: 프로필 마지막 업데이트 시간 (수정 시점으로 자동 갱신)

현재 사용자 프로필 수정​

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

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

Headers​

HeaderTypeDescriptionRequired
AuthorizationBearer {accessToken}사용자 인증을 통해 발급받은 액세스 토큰입니다.Yes
Content-Typeapplication/json요청 본문의 미디어 타입입니다.Yes

Request Body​

모든 필드는 선택적(optional)이며, 수정하고자 하는 필드만 포함하면 됩니다.

필드타입설명RequiredValidation
userNamestring사용자 이름No-
languagestring언어 코드 (지원: ko-KR, de-DE, en-US)NoEnum: ko-KR, de-DE, en-US
timezoneIdstring타임존 ID (IANA 형식, 예: "Asia/Seoul")NoPattern: ^[A-Za-z_]+/[A-Za-z_]+$
언어만 수정하는 경우
{
  "language": "en-US"
}
타임존만 수정하는 경우
{
  "timezoneId": "Europe/Berlin"
}
모든 필드를 수정하는 경우
{
  "userName": "John Doe",
  "language": "en-US",
  "timezoneId": "America/New_York"
}

Responses​

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

프로필 수정 성공:

{
  "userId": "user_123",
  "userName": "John Doe",
  "language": "en-US",
  "timezoneId": "America/New_York",
  "createdAt": 1711929600000,
  "updatedAt": 1714527000000
}
필드타입설명
userIdstring사용자 ID
userNamestring수정된 사용자 이름 (선택적, null 가능)
languagestring수정된 언어 설정 (예: "ko-KR", "en-US", "de-DE")
timezoneIdstring수정된 타임존 ID (예: "Asia/Seoul", "Europe/Berlin", "America/New_York")

| createdAt | number | 프로필 생성 시간 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64) | | updatedAt | number | 프로필 마지막 업데이트 시간 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64) |

400 Bad Request - 잘못된 요청 데이터

예시: 유효하지 않은 언어 코드 (INVALID_LANGUAGE_CODE - 7011)

{
  "code": 7011,
  "message": "INVALID_LANGUAGE_CODE",
  "detail": "지원하지 않는 언어 코드입니다. 허용된 값: ko-KR, de-DE, en-US",
  "metadata": {
    "language": "invalid-code"
  }
}

예시: 유효하지 않은 타임존 형식 (INVALID_TIMEZONE_FORMAT - 7012)

{
  "code": 7012,
  "message": "INVALID_TIMEZONE_FORMAT",
  "detail": "유효하지 않은 타임존 형식입니다. IANA 타임존 형식을 사용해주세요.",
  "metadata": {
    "timezoneId": "Invalid/Timezone"
  }
}
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: PATCH
  • Path: /v1/users/{userId}/profile
  • 인증: 관리자 액세스 토큰 (adminToken) 필요

Path Parameters​

ParameterTypeDescriptionRequired
userIdstring수정할 사용자의 ID (UUID 형식)Yes

Headers​

HeaderTypeDescriptionRequired
AuthorizationBearer {adminToken}관리자 인증을 통해 발급받은 액세스 토큰입니다.Yes
Content-Typeapplication/json요청 본문의 미디어 타입입니다.Yes

Request Body​

요청 본문은 현재 사용자 프로필 수정과 동일합니다.

Responses​

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

관리자용 프로필 수정 성공:

{
  "userId": "user_456",
  "userName": "김철수",
  "language": "ko-KR",
  "timezoneId": "Asia/Seoul",
  "createdAt": 1711929600000,
  "updatedAt": 1714527000000
}

응답 필드는 현재 사용자 프로필 수정과 동일합니다.

400 Bad Request - 잘못된 요청

예시: UUID 형식 오류

{
  "message": "Validation failed (uuid is expected)",
  "error": "Bad Request",
  "statusCode": 400
}

예시: 유효하지 않은 언어 코드 (INVALID_LANGUAGE_CODE - 7011)

{
  "code": 7011,
  "message": "INVALID_LANGUAGE_CODE",
  "detail": "지원하지 않는 언어 코드입니다. 허용된 값: ko-KR, de-DE, en-US",
  "metadata": {
    "userId": "user_456",
    "language": "invalid-code"
  }
}
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 PATCH "https://api.example.com/v1/users/me/profile" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en-US"
  }'

타임존 정보 변경:

curl -X PATCH "https://api.example.com/v1/users/me/profile" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "timezoneId": "Europe/Berlin"
  }'

관리자용 특정 사용자 프로필 수정​

curl -X PATCH "https://api.example.com/v1/users/user_456/profile" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "김철수",
    "language": "ko-KR",
    "timezoneId": "Asia/Seoul"
  }'

참고사항​

  • 선택적 업데이트: 모든 필드는 선택적이며, 수정하고자 하는 필드만 요청 본문에 포함하면 됩니다.
  • 타임존 정보: timezoneId는 IANA Time Zone Database의 표준 타임존 식별자를 사용하며, UTC 오프셋은 시스템에서 자동으로 계산됩니다.
  • 언어 코드: 지원되는 언어는 ko-KR (한국어), de-DE (독일어), en-US (영어)로 제한됩니다.
  • 원자성: 프로필 수정은 원자적(atomic) 작업으로 처리되며, 일부 필드 수정 실패 시 전체 작업이 롤백됩니다.
  • 캐싱: 프로필 정보는 성능 최적화를 위해 캐싱될 수 있으며, 수정 후 캐시가 자동으로 무효화됩니다.
  • 이벤트 발행: 프로필 수정 성공 시 내부 이벤트가 발행되어 관련 서비스들이 변경 사항을 감지할 수 있습니다.