API 개요

소개

이 문서는 시스템의 API 설계 원칙과 공통 사항을 정의합니다. 모든 API는 이 문서에서 정의한 규칙을 따라야 합니다.

API 설계 원칙

1. RESTful 원칙

• 리소스 중심의 URL 설계
• 적절한 HTTP 메서드 사용
• 상태 코드의 올바른 사용
• HATEOAS 원칙 준수

2. 버전 관리

• 모든 API는 전역 버전 프리픽스를 사용 (현재 v1)
• 컨트롤러 코드 및 문서 작성 시 버전 프리픽스 생략
• 클라이언트 호출 시 전체 URL에 버전 프리픽스 포함 (예: https://api.example.com/v1/users)
• 하위 호환성이 깨질 경우 메이저 버전 업

3. 명명 규칙

• 복수형 명사로 리소스 표현 (예: /users)
• 소문자와 하이픈 사용 (예: /user-profiles)
• 일관된 명명 규칙 사용

공통 응답 형식

단일 객체 응답

단일 객체 응답은 불필요한 중첩 없이 데이터를 직접 반환합니다.

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

컬렉션 응답

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

{
  "items": [
    {
      "id": "user1",
      "name": "John Doe"
    },
    {
      "id": "user2",
      "name": "Jane Smith"
    }
  ],
  "metadata": {
    "totalCount": 42,
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 5
  }
}

에러 응답

{
  "code": 1000,
  "message": "RESOURCE_NOT_FOUND",
  "detail": "The requested resource was not found in the system",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

유효성 검증 에러 응답 예시

{
  "code": 1001,
  "message": "VALIDATION_ERROR",
  "detail": "The request contains invalid parameters",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    },
    {
      "field": "password",
      "message": "Password must be at least 8 characters"
    }
  ]
}

HTTP 상태 코드

상태 코드	설명	사용 시점
200	OK	요청 성공
201	Created	리소스 생성 성공
204	No Content	성공했지만 응답 본문 없음
400	Bad Request	잘못된 요청
401	Unauthorized	인증 필요
403	Forbidden	권한 없음
404	Not Found	리소스를 찾을 수 없음
500	Internal Server Error	서버 오류

API 문서화

1. 문서 구조

• API 개요
• 요청/응답 형식
• 에러 코드
• 예제 코드
• 테스트 방법

2. Swagger/OpenAPI

• API 문서 자동화
• 테스트 환경 제공
• 스키마 정의
• 예제 포함

보안

1. 인증

• JWT 기반 인증
• API 키 인증 (B2B)
• OAuth2.0 지원
• 컨센트 토큰 기반 권한 위임

2. 권한 관리

• 역할 기반 접근 제어 (RBAC)
• 리소스별 권한 관리
• API 엔드포인트별 권한 설정
• 컨센트 토큰 기반 범위 제한

3. IAM 역할 및 권한

• 표준화된 역할 정의
  • System Admin: 전체 시스템 관리 권한
  • IAM Admin: 사용자 권한 관리
  • Org Admin: 특정 조직 내 관리 권한
  • Team Admin: 특정 팀 내 관리 권한
  • Regular User: 일반 사용자 권한
• 모든 API는 IAM 역할 기반 접근 제어 적용
• 역할별 접근 범위 정의
  • 전체 접근: 모든 리소스 접근
  • 범위 내 접근: 할당된 조직/팀 내 리소스만 접근
  • 자신만 접근: 자신의 리소스만 접근
• 모든 도메인별 API 문서에는 접근 권한 매트릭스 포함 필수

4. 컨센트 토큰

• 사용자 동의 기반 권한 위임
• 범위(scope) 기반 접근 제어
• 목적 기반 권한 관리
• 만료 시간 자동 관리

성능

1. 응답 시간

• 95% 요청: 300ms 이내
• 99% 요청: 500ms 이내
• 최대 응답 시간: 1초

2. 처리량

• 초당 최소 1000 요청 처리
• 동시 사용자 10000명 지원

3. 캐싱

• 응답 캐싱 전략
• ETags 사용
• 캐시 무효화 정책

로깅 및 모니터링

1. 표준 로그 포맷

{
  "level": "info",
  "message": "API 요청 처리 완료",
  "timestamp": 1679471431000,
  "service": "auth",
  "event": "API_REQUEST",
  "correlation_id": "corr-456",
  "user_id": "user123",
  "resource_id": "123",
  "resource_type": "user",
  "metadata": {
    "method": "GET",
    "url": "/v1/users/123",
    "status": 200,
    "duration_ms": 45
  }
}

2. 상관 관계 ID

• 모든 API 요청은 x-correlation-id 헤더를 통해 상관 관계 ID 전달
• 상관 관계 ID가 없는 경우 자동 생성
• 응답 헤더에 동일한 상관 관계 ID 포함
• 분산 추적을 위한 핵심 요소

3. 로깅 레벨별 사용 사례

• ERROR: API 오류, 예외 발생
• WARN: 비즈니스 규칙 위반, 잠재적 문제
• INFO: API 호출 시작/종료, 주요 비즈니스 이벤트
• DEBUG: 요청/응답 상세 내용, 처리 흐름 정보
• TRACE: 매우 상세한 진단 정보

4. 성능 측정

• 모든 API 호출에 대한 처리 시간 기록
• 임계값 초과 시 자동 경고
• 주기적인 성능 보고서 생성
• 병목 구간 식별 및 최적화

5. 에러 추적

• 구조화된 에러 로깅
• 스택 트레이스 포함 (개발 환경)
• 에러 발생 컨텍스트 정보 기록
• 재발 패턴 분석

API 도메인 구조

/v1
├── /users                        # 사용자 관리
│   ├── /{userId}                # 사용자 정보 관리
│   ├── /{userId}/devices        # 디바이스 관리
│   └── /{userId}/password       # 비밀번호 관리
│
├── /auth                         # 인증 도메인
│   ├── /app                   # 앱 인증 API
│   │   ├── /challenge         # 챌린지 요청
│   │   └── /complete-challenge   # 챌린지 응답 검증 및 토큰 발급
│   ├── /terms                   # 약관 관리
│   │   └── /agreement          # 약관 동의 저장
│   ├── /email                   # 이메일 인증
│   │   ├── /verification-code  # 인증 코드 발송
│   │   └── /verify             # 인증 코드 확인
│   ├── /login                   # 로그인
│   ├── /logout                  # 로그아웃
│   ├── /token                   # 토큰 관리
│   │   ├── /refresh            # 토큰 갱신
│   │   └── /validate           # 토큰 검증
│   ├── /permissions            # 권한 관리
│   │   └── /check              # 권한 확인
│   └── /consent-tokens         # 컨센트 토큰
│       └── /device             # 디바이스 기반 컨센트 토큰
│
├── /iam                          # IAM 관리
│   ├── /roles                   # 역할 관리
│   │   ├── /{roleId}           # 역할 정보 관리
│   │   └── /{roleId}/permissions # 역할별 권한 관리
│   ├── /users                   # 사용자 역할 관리
│   │   └── /{userId}/roles     # 사용자별 역할 할당
│   ├── /organizations          # 조직 관리
│   │   ├── /{orgId}            # 조직 정보 관리
│   │   └── /{orgId}/members    # 조직 멤버 관리
│   └── /teams                   # 팀 관리
│       ├── /{teamId}           # 팀 정보 관리
│       └── /{teamId}/members   # 팀 멤버 관리
│
├── /time-machine                 # 시간 관리
│   ├── /current-time            # 현재 시간 조회
│   ├── /set-time                # 시간 설정
│   ├── /move                    # 시간 이동
│   ├── /reset                   # 시간 초기화
│   ├── /sync                    # 시간 동기화 실행
│   │   └── /status             # 동기화 상태 조회
│   └── /settings                # 설정 관리
│
├── /access-codes                 # 접근 코드
│   ├── /validate                # 코드 검증
│   ├── /{codeId}/use            # 코드 사용
│   ├── /batch                   # 일괄 코드 생성
│   └── /personal-data           # 개인정보 관리
│       └── /{userId}            # 사용자별 개인정보
│
└── /security                    # 보안 관리

변경 이력

버전	날짜	작성자	변경 내용
0.1.2	2025-04-05	bok@weltcorp.com	DDD 구조에 맞게 API 링크 업데이트
0.1.1	2025-03-16	bok@weltcorp.com	IAM 추가
0.1.0	2025-03-16	bok@weltcorp.com	최초 작성