본문으로 건너뛰기

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는 전역 버전 프리픽스를 사용 (현재 v1)
  • 컨트롤러 코드 작성 시: 버전 프리픽스 생략 (전역 설정이 적용됨) 
    // NestJS 컨트롤러 예시 (프리픽스 생략)
    @Controller('users')
    export class UsersController {
      @Get()
      findAll() { ... }
    }
  • 문서 작성 시: 경로에 버전 프리픽스 생략 
    # 사용자 API

    ## 사용자 목록 조회
    - 경로: /users
    - 메서드: GET
  • 클라이언트 호출 시: 전체 URL에 버전 프리픽스 포함 
    GET https://api.example.com/v1/users

2.2 버전 관리 원칙​

  • 하위 호환성이 깨질 경우 메이저 버전 업 (예: v1 → v2)
  • 메이저 버전은 전역 프리픽스로 관리
  • 마이너 버전은 헤더로 처리 (X-API-Version)
  • 최대 2개 이전 버전까지만 지원

2.3 버전 마이그레이션​

  • 새 버전 출시 시 최소 3개월의 마이그레이션 기간 제공
  • 마이그레이션 기간 중 사용자에게 새 버전으로의 이전 안내
  • 구 버전 지원 종료 최소 1개월 전 공지

3. 응답 형식​

3.1 단일 객체 응답​

// 단일 객체는 중첩 없이 직접 반환
type SingleResponse<T> = T;

예시:

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

3.2 컬렉션 응답​

interface CollectionResponse<T> {
  items: T[];
  metadata: {
    totalCount: number;
    currentPage: number;
    pageSize: number;
    totalPages: number;
  }
}

예시:

{
  "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
  }
}

3.3 에러 응답​

interface ErrorResponse {
  code: number;      // 애플리케이션 에러 코드
  message: string;   // 에러 메시지
  detail?: string;   // 상세 설명
  metadata?: Record<string, any>; // 오류 관련 추가 메타데이터
}

예시:

{
  "code": 1001,
  "message": "INVALID_INPUT",
  "detail": "Invalid input parameters",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ],
  "metadata": {
    "exampleKey": "exampleValue"
  }
}

3.4 시간 표시 형식​

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

// 시간 필드의 타입 정의
type Timestamp = number; // 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
}

Unix 타임스탬프 사용의 이점:

  • 타임존 독립적인 표현
  • 클라이언트 측 계산 용이성
  • 정렬 및 비교 연산 단순화
  • 데이터 크기 최소화

참고: 시간 데이터 처리에 대한 자세한 내용은 데이터 타입 가이드라인을 참조하세요.

4. 페이지네이션​

4.1 요청 파라미터​

  • page: 페이지 번호 (1부터 시작)
  • size: 페이지 크기
  • sort: 정렬 기준 (예: "name:asc,createdAt:desc")

4.2 페이지네이션 응답​

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

// CollectionResponse의 metadata 필드 활용
{
  "items": [...],
  "metadata": {
    "totalCount": 42,    // 전체 아이템 수
    "currentPage": 1,    // 현재 페이지 (1부터 시작)
    "pageSize": 10,      // 페이지 크기
    "totalPages": 5      // 전체 페이지 수
  }
}

5. 검색 및 필터링​

5.1 검색 파라미터​

  • q: 검색어
  • filter: 필터 조건 (예: "status:active,type:premium")

5.2 필터 연산자​

  • eq: 같음
  • ne: 같지 않음
  • gt: 초과
  • gte: 이상
  • lt: 미만
  • lte: 이하
  • in: 포함
  • nin: 미포함

6. 보안​

6.1 인증​

  • Bearer 토큰 사용
  • Authorization 헤더 사용
  • 토큰 만료 시간 설정

6.2 권한 검사​

  • RBAC (Role-Based Access Control) 구현
  • 리소스별 권한 정의
  • 세분화된 접근 제어

6.3 IAM 역할 관리​

  • 모든 API는 IAM 역할 기반의 접근 제어 적용
  • IAM 역할은 아래와 같은 계층 구조로 정의
    • System Admin: 전체 시스템 관리 권한
    • IAM Admin: 사용자 권한 관리
    • Org Admin: 특정 조직 내 관리 권한
    • Team Admin: 특정 팀 내 관리 권한
    • Regular User: 일반 사용자 권한
  • 각 역할별 접근 가능 범위 지정
    • 전체 접근: 모든 리소스 접근 가능
    • 범위 내 접근: 할당된 조직/팀 범위 내에서만 접근 가능
    • 자신만 접근: 자신의 리소스에만 접근 가능

6.4 권한 위임 및 승인​

  • 역할 할당/회수 요청 시 승인 프로세스 적용
  • 승인 레벨 정의 (자동 승인, 단일 승인, 다중 승인)
  • 권한 남용 방지를 위한 감사 로깅

7. 성능​

7.1 캐싱​

  • ETag 헤더 사용
  • Cache-Control 헤더 설정
  • 적절한 캐시 만료 시간 설정
  • Cloud CDN 활용 고려

7.2 압축​

  • gzip 압축 사용
  • 대용량 응답 처리
  • 청크 전송 고려

7.3 Cloud Run 최적화​

  • 콜드 스타트 최소화
    • 이미지 크기 최적화
    • 초기화 시간 단축
    • 워밍업 엔드포인트 구현
  • 자동 스케일링 설정
    • 최소/최대 인스턴스 수 설정
    • 동시성 레벨 조정
  • 메모리 사용량 최적화
    • 메모리 누수 방지
    • 가비지 컬렉션 튜닝
  • 요청 타임아웃 설정
    • Cloud Run 최대 타임아웃: 60분
    • 일반적인 API 응답: 30초 이내

8. 문서화​

8.1 Swagger/OpenAPI​

  • 모든 API 엔드포인트 문서화
  • 요청/응답 스키마 정의
  • 예제 포함

8.2 에러 코드​

  • 모든 에러 코드 문서화
  • 에러 발생 조건 설명
  • 해결 방법 제시

8.3 접근 권한 매트릭스​

  • 모든 도메인 API 문서에는 엔드포인트 접근 권한 매트릭스 포함
  • 매트릭스 형식으로 각 엔드포인트별 역할 접근 권한 명시
  • 권한 표기는 다음과 같은 기호로 통일
    • ✓: 접근 가능
    • ✘: 접근 불가
    • 범위 내: 할당된 조직/팀 범위 내에서만 접근 가능
    • 자신만: 자신의 데이터에만 접근 가능
  • 권한 제한이 있는 경우 괄호 안에 추가 설명 기재 (예: 범위 내(제한적))

9. 배포 환경​

9.1 Cloud Run 설정 (TBD)​

  • 리전: europe-west3 (프랑크푸트트)
  • 최소 인스턴스: 0
  • 최대 인스턴스: 자동 스케일링
  • 메모리: 512MB ~ 2GB
  • CPU: 1-2
  • 타임아웃: 300초
  • HTTPS 강제
  • 인그레스: all
  • VPC 연결: Serverless VPC Access

9.2 환경 구성​

  • 개발(dev)
    • 도메인: api-dev.example.com
    • 자동 배포 (main 브랜치)
  • 스테이지(stage)
    • 도메인: api-stage.example.com
    • 수동 배포 (릴리즈 태그)
  • 프로덕션(prod)
    • 도메인: api.example.com
    • 수동 배포 (릴리즈 태그)

9.3 모니터링​

  • Cloud Monitoring
    • 요청 지연 시간
    • 에러율
    • 인스턴스 수
    • 메모리 사용량
  • Cloud Logging
    • 구조화된 로깅
    • 에러 추적
    • 감사 로그

10. 로깅 규약​

10.1 로그 출력 전략​

  • 모든 API 컴포넌트는 공통 로깅 인프라(LogPublisherModule) 사용
  • 환경별 로그 출력 전략 자동 적용
    • 로컬 환경: Winston 기반 파일/콘솔 출력
    • 클라우드 환경: Pub/Sub 기반 Cloud Logging 통합

10.2 상관 관계 ID 처리​

  • 모든 API 요청은 x-correlation-id 헤더 포함
  • 헤더가 없는 경우 자동 생성하여 응답 헤더에 포함
  • 모든 로그에 correlation_id 필드 포함
  • 마이크로서비스 간 호출 시 상관 관계 ID 전파

10.3 구조화된 로그 형식​

  • 모든 로그는 JSON 형식으로 출력
  • 표준 필드 집합 준수 (timestamp, level, service, event, message 등)
  • 도메인별 메타데이터 필드 표준화

10.4 로깅 시점 및 레벨​

  • API 호출 시작/종료: INFO 레벨 (API_REQUEST, API_RESPONSE 이벤트)
  • 주요 비즈니스 이벤트: INFO 레벨 (도메인별 이벤트 명명 규칙 준수)
  • 비즈니스 규칙 위반: WARN 레벨
  • API 오류: ERROR 레벨
  • 상세 디버깅 정보: DEBUG 레벨 (프로덕션 환경에서는 비활성화)

10.5 에러 로깅​

  • 모든 예외는 표준화된 형식으로 로깅
  • 에러 코드, 메시지, 스택 트레이스(개발 환경) 포함
  • 민감 정보 자동 마스킹 처리
  • 에러 발생 컨텍스트 정보(사용자 ID, 리소스 ID 등) 포함

변경 이력​

버전날짜작성자변경 내용
0.1.02025-03-16bok@weltcorp.com최초 작성
0.2.02025-03-19bok@weltcorp.comCloud Run 관련 내용 추가 및 Kubernetes 관련 내용 제거
0.3.02025-03-20bok@weltcorp.comIAM 및 접근 권한 매트릭스 관련 내용 추가