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

API 규약

이 문서는 모바일 개발자가 백엔드 API를 사용할 때 알아야 할 공통적인 규약을 설명합니다.

1. API 설계 원칙​

1.1 URL 구조​

  • 리소스는 복수형 명사를 사용합니다 (예: /users, /orders)
  • 다중 단어는 케밥 케이스로 작성합니다 (예: /user-profiles)
  • 계층 구조는 경로로 표현합니다 (예: /users/{userId}/orders)

1.2 HTTP 메서드​

  • GET: 리소스 조회
  • POST: 리소스 생성
  • PUT: 리소스 전체 수정
  • PATCH: 리소스 부분 수정
  • DELETE: 리소스 삭제

1.3 상태 코드​

  • 200 OK: 성공적인 GET, PUT, PATCH 요청
  • 201 Created: 성공적인 POST 요청
  • 204 No Content: 성공적인 DELETE 요청
  • 400 Bad Request: 잘못된 요청
  • 401 Unauthorized: 인증 필요
  • 403 Forbidden: 권한 없음
  • 404 Not Found: 리소스 없음
  • 409 Conflict: 리소스 충돌
  • 500 Internal Server Error: 서버 오류

2. 버전 관리​

2.1 버전 표기​

모든 API는 URL에 지역 코드와 버전 프리픽스(현재 de/v1)를 포함합니다. 지역 코드 de는 독일(Germany)을 나타냅니다.

// 클라이언트 호출 예시
GET https://api-{dev|stage|prod}.sleepq.ai/de/v1/users
모바일 개발자 참고사항

API 호출 시 항상 지역 코드와 버전 프리픽스를 포함해야 합니다. 이 프리픽스가 생략된 요청은 처리되지 않습니다.

2.2 버전 관리 원칙​

  • 하위 호환성이 깨질 경우 메이저 버전이 업데이트됩니다 (예: v1 → v2)
  • 메이저 버전은 URL 프리픽스로 관리됩니다
  • 마이너 버전은 X-API-Version 헤더로 처리됩니다
  • 최대 2개 이전 버전까지만 지원됩니다
모바일 앱 개발 시 고려사항

새로운 API 버전이 출시될 때 앱 업데이트가 필요할 수 있습니다. 앱 내에서 지원하는 API 버전을 설정 파일로 관리하고, 필요시 사용자에게 업데이트 알림을 표시하는 것이 좋습니다.

3. 응답 형식​

3.1 단일 객체 응답​

단일 객체 응답은 중첩 없이 직접 반환됩니다.

{
  "id": "user1",
  "name": "John Doe",
  "email": "john@example.com"
}

3.2 컬렉션 응답​

컬렉션 응답은 items 배열과 메타데이터를 포함합니다.

{
  "items": [
    {
      "id": "user1",
      "name": "John Doe",
      "email": "john@example.com"
    },
    {
      "id": "user2",
      "name": "Jane Smith",
      "email": "jane@example.com"
    }
  ],
  "metadata": {
    "totalCount": 42,
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 5
  }
}
모바일에서의 활용

컬렉션 응답의 metadata 정보를 활용하여 무한 스크롤이나 페이지네이션 UI를 구현할 수 있습니다.

3.3 에러 응답​

에러 응답은 코드, 메시지 및 상세 정보를 포함합니다. errors(필드별 유효성 검증 오류) 필드는 선택적으로 포함될 수 있습니다.

{
  "code": 1001,
  "message": "INVALID_INPUT",
  "detail": "Invalid input parameters",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}
에러 처리 주의사항

모바일 앱에서는 에러 코드별로 적절한 사용자 피드백을 제공해야 합니다. 서버에서 받은 에러 메시지를 그대로 표시하지 말고, 사용자 친화적인 메시지로 변환하세요.

3.4 시간 표시 형식​

모든 API 응답에서 날짜와 시간은 13자리 Unix 타임스탬프(밀리초)로 표시됩니다.

{
  "id": "order123",
  "userId": "user456",
  "status": "completed",
  "createdAt": 1679471431000,  // 2023-03-22 09:43:51 UTC
  "updatedAt": 1679471490000   // 2023-03-22 09:44:50 UTC
}
시간 표시 변환

모바일 앱에서는 받은 타임스탬프를 사용자의 로컬 시간대와 선호하는 형식으로 변환하여 표시해야 합니다.

// Swift 예시
let timestamp = 1679471431000
let date = Date(timeIntervalSince1970: Double(timestamp) / 1000)
let formatter = DateFormatter()
formatter.dateStyle = .medium
formatter.timeStyle = .short
let displayString = formatter.string(from: date)
// Kotlin 예시
val timestamp = 1679471431000L
val date = Date(timestamp)
val formatter = SimpleDateFormat("yyyy-MM-dd HH:mm", Locale.getDefault())
val displayString = formatter.format(date)

4. 페이지네이션​

4.1 요청 파라미터​

  • page: 페이지 번호 (1부터 시작)
  • size: 페이지 크기
  • sort: 정렬 기준 (예: "name:asc,createdAt:desc")
GET /de/v1/users?page=2&size=20&sort=name:asc,createdAt:desc

4.2 페이지네이션 응답​

컬렉션 응답의 metadata 필드를 통해 페이지네이션 정보가 제공됩니다.

{
  "items": [...],
  "metadata": {
    "totalCount": 42,    // 전체 아이템 수
    "currentPage": 1,    // 현재 페이지 (1부터 시작)
    "pageSize": 10,      // 페이지 크기
    "totalPages": 5      // 전체 페이지 수
  }
}
모바일 UI 구현

페이지네이션 정보를 활용하여 다음과 같은 UI를 구현할 수 있습니다:

  • 페이지 인디케이터
  • "다음" 또는 "이전" 버튼 활성화/비활성화
  • 무한 스크롤 (마지막 페이지 감지)

5. 검색 및 필터링​

5.1 검색 파라미터​

  • q: 검색어
  • filter: 필터 조건 (예: "status:active,type:premium")
GET /de/v1/users?q=john&filter=status:active,type:premium

5.2 필터 연산자​

  • eq: 같음
  • ne: 같지 않음
  • gt: 초과
  • gte: 이상
  • lt: 미만
  • lte: 이하
  • in: 포함
  • nin: 미포함
GET /de/v1/products?filter=price:gte:1000,price:lte:5000,category:in:electronics,books

6. 보안​

6.1 인증​

  • 모든 인증된 API 요청에는 Bearer 토큰을 사용합니다
  • Authorization 헤더에 토큰을 포함해야 합니다
  • 토큰은 일정 시간 후 만료됩니다
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
모바일 앱에서의 토큰 관리
  • 토큰은 안전한 저장소(iOS의 Keychain, Android의 EncryptedSharedPreferences)에 저장해야 합니다
  • 토큰 만료 시 자동으로 갱신하는 매커니즘을 구현해야 합니다
  • 로그아웃 시 토큰을 삭제해야 합니다

6.2 권한 검사​

API 엔드포인트마다 접근에 필요한 권한이 다릅니다. 모바일 앱은 사용자 권한에 따라 UI를 적절히 조정해야 합니다.

7. 성능 최적화​

7.1 캐싱​

  • ETag 헤더를 활용하여 클라이언트 캐싱을 구현할 수 있습니다
  • Cache-Control 헤더를 확인하여 적절한 캐싱 전략을 수립하세요
모바일 앱 캐싱 전략
  • 자주 변경되지 않는 데이터는 로컬에 캐싱하여 네트워크 요청을 줄이세요
  • 캐시된 데이터의 유효 기간을 설정하고 정기적으로 갱신하세요
  • 오프라인 사용을 위한 캐싱 전략을 고려하세요

7.2 데이터 압축​

API 응답은 gzip으로 압축될 수 있으므로, 클라이언트에서 이를 처리할 수 있어야 합니다.

모바일 개발자를 위한 모범 사례​

  1. 네트워크 상태 처리: 오프라인 상태와 불안정한 네트워크 상태를 고려하여 설계하세요
  2. 배터리 효율성: 불필요한 API 호출을 최소화하세요
  3. 에러 처리: 모든 API 에러에 대해 사용자 친화적인 피드백을 제공하세요
  4. 응답 시간: API 응답이 지연될 경우 로딩 인디케이터를 표시하세요
  5. 토큰 관리: 토큰의 안전한 저장과 갱신을 관리하세요
  6. 버전 호환성: 앱 버전과 API 버전의 호환성을 관리하세요