API 레퍼런스 개요

소개

이 섹션에서는 모바일 애플리케이션 개발에 필요한 백엔드 API의 상세 명세를 제공합니다. 각 API 엔드포인트의 요청 형식, 응답 형식, 인증 요구사항 및 에러 처리 방법을 설명합니다.

API 기본 정보

기본 URL

모든 API 요청은 다음 기본 URL을 사용합니다:

• 개발 환경: https://dta-wir-{domain}-api-{dev}.weltcorp.com/v2
• 프로덕션 환경: https://dta-wir-{domain}-api-{prod}.weltcorp.com/v2

요청 형식

• API 요청 본문은 JSON 형식을 사용합니다.
• Content-Type 헤더는 application/json으로 설정해야 합니다.

응답 형식

API 응답은 다음과 같은 일관된 형식을 따릅니다:

• 단일 객체 요청의 경우, 객체가 직접 반환됩니다.
• 컬렉션 요청의 경우, items 배열과 metadata 객체가 포함됩니다.
• 에러 응답의 경우, code, message, detail 등의 필드가 포함됩니다.

도메인별 API

본 API 레퍼런스는 다음과 같은 도메인별 API를 포함합니다:

도메인	설명	문서 링크
사용자 (User)	사용자 정보 관리	사용자 API
인증 (Auth)	인증 및 토큰 관리	인증 API
설문지 (Questionnaire)	설문지 번들 및 응답 관리	설문지 API
수면 (Sleep)	수면 데이터 및 분석	수면 API
모바일 (Mobile)	모바일 앱 설정 및 관리	모바일 API
IAM	권한 및 역할 관리	IAM API
학습 (Learning)	학습 콘텐츠 및 진행도	학습 API
시간 (TimeMachine)	시스템 시간 관리	시간 API
접근 코드 (Access Code)	접근 코드 관리	접근 코드 API

API 호출 예시

각 API 설명에는 다음과 같은 형식으로 호출 예시가 포함됩니다:

cURL 예시

curl -X GET "https://dta-wir-crm-api.weltcorp.com/v2/auth/tokens/md/access" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Swift (iOS) 예시

let url = URL(string: "https://dta-wir-crm-api.weltcorp.com/v2/auth/tokens/md/access")!
var request = URLRequest(url: url)
request.httpMethod = "GET"
request.addValue("Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", forHTTPHeaderField: "Authorization")
request.addValue("application/json", forHTTPHeaderField: "Content-Type")

URLSession.shared.dataTask(with: request) { data, response, error in
    if let data = data {
        do {
            let user = try JSONDecoder().decode(User.self, from: data)
            print("User: \(user)")
        } catch {
            print("Error decoding: \(error)")
        }
    }
}.resume()

Kotlin (Android) 예시

val retrofit = Retrofit.Builder()
    .baseUrl("https://dta-wir-crm-api.weltcorp.com/v2/auth/tokens/md/access")
    .addConverterFactory(GsonConverterFactory.create())
    .build()

val service = retrofit.create(ApiService::class.java)
val call = service.getUser("Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")

call.enqueue(object : Callback<User> {
    override fun onResponse(call: Call<User>, response: Response<User>) {
        if (response.isSuccessful) {
            val user = response.body()
            println("User: $user")
        }
    }

    override fun onFailure(call: Call<User>, t: Throwable) {
        println("Error: ${t.message}")
    }
})

에러 처리

API 호출 시 발생할 수 있는 일반적인 에러 코드는 다음과 같습니다:

HTTP 상태 코드	설명
400 Bad Request	잘못된 요청 파라미터나 본문
401 Unauthorized	인증 필요 또는 인증 실패
403 Forbidden	접근 권한 없음
404 Not Found	리소스를 찾을 수 없음
409 Conflict	리소스 충돌 (예: 중복된 리소스 생성 시도)
429 Too Many Requests	요청 횟수 제한 초과
500 Internal Server Error	서버 내부 오류

자세한 에러 처리 방법은 에러 처리 페이지를 참조하세요.

제한 사항

• API 요청 속도는 IP당 분당 100회로 제한됩니다.
• 대량의 데이터 요청은 페이지네이션을 사용해야 합니다.
• 파일 업로드 크기는 최대 10MB로 제한됩니다.

도움말 및 지원

API 사용 중 문제가 발생하면 다음 리소스를 참조하세요:

• 자주 묻는 질문 (FAQ) (문서 없음)
• API 가이드라인
• API 규약

기술 지원이 필요한 경우 api-support@sleepq.ai으로 문의하세요.