Skip to main content

API 버전 관리

Multi-SaaS Kit API의 버전 관리 전략입니다.

개요​

항목설명
버전 관리 방식URL 경로 (/api/v1/...)
현재 버전v1
지원 기간최소 24개월

버전 관리 방식​

URL 경로 방식​

모든 API 엔드포인트는 URL에 버전을 포함합니다:

GET /api/v1/users
GET /api/v1/tenants
GET /api/v2/users    (향후)

왜 URL 방식인가?​

방식장점단점
URL 경로명확함, 캐싱 용이, 디버깅 쉬움URL 길어짐
HeaderURL 깔끔디버깅 어려움, 캐싱 복잡
Query Parameter유연함표준 아님, 실수 가능

버전 생명주기​

┌─────────────────────────────────────────────────────────┐
│  Current (현재)                                         │
│  - 모든 신규 기능 추가                                   │
│  - 버그 수정 및 보안 패치                                │
│  - 기간: 새 버전 출시까지                                │
└────────────────────────┬────────────────────────────────┘
                         │ 새 버전 출시
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Maintained (유지보수)                                  │
│  - 신규 기능 없음                                        │
│  - 버그 수정 및 보안 패치만                              │
│  - 기간: 12개월                                         │
└────────────────────────┬────────────────────────────────┘
                         │ 12개월 후
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Deprecated (지원 중단 예정)                             │
│  - 보안 패치만                                          │
│  - 마이그레이션 경고 헤더 추가                           │
│  - 기간: 6개월                                          │
└────────────────────────┬────────────────────────────────┘
                         │ 6개월 후
                         ▼
┌─────────────────────────────────────────────────────────┐
│  End of Life (지원 종료)                                │
│  - 410 Gone 응답 반환                                   │
│  - 문서에서 제거                                        │
└─────────────────────────────────────────────────────────┘

현재 버전 상태​

버전상태출시일지원 종료
v1Current2024-01-
v2계획 중미정-

버전별 변경 사항​

v1 (현재)​

핵심 기능:

  • 인증 API (Sanctum 기반)
  • 사용자 CRUD
  • 테넌트 CRUD
  • 권한 시스템 (Level 0~6, ADR-058)
  • 웹훅 시스템

v2 (계획)​

예정 변경 사항:

  • GraphQL 지원 (선택)
  • Batch 요청 지원
  • 실시간 구독 (WebSocket)

버전 확인​

응답 헤더​

모든 API 응답에 버전 정보가 포함됩니다:

HTTP/1.1 200 OK
X-API-Version: v1
X-API-Deprecated: false

Deprecated 버전 응답​

지원 중단 예정 버전 사용 시:

HTTP/1.1 200 OK
X-API-Version: v1
X-API-Deprecated: true
X-API-Sunset-Date: 2026-06-01
X-API-Deprecation-Notice: This API version will be deprecated. Please migrate to v2.

마이그레이션 가이드​

v1 → v2 마이그레이션 (예정)​

버전 업그레이드 시 변경 사항:

# 엔드포인트 변경
- GET /api/v1/users
+ GET /api/v2/users

# 응답 형식 변경 (예시)
{
  "success": true,
- "data": { ... }
+ "result": { ... },
+ "meta": { "version": "v2" }
}

호환성 유지 기간​

  • 기존 API: 최소 18개월 동안 동작 보장
  • 경고 기간: 6개월 전 Deprecation 공지
  • 마이그레이션 도구: 변환 스크립트 제공 예정

버전 선택 가이드​

신규 프로젝트​

항상 최신 Current 버전 사용:

# 권장
GET /api/v1/users

# 비권장 (지원 종료 버전)
GET /api/v0/users  # 410 Gone

기존 프로젝트​

  1. 현재 사용 버전 확인
  2. Deprecation 공지 확인
  3. 테스트 환경에서 새 버전 테스트
  4. 점진적 마이그레이션

Breaking Changes 정책​

Breaking Change로 간주하는 것​

  • 엔드포인트 URL 변경
  • 필수 파라미터 추가
  • 응답 필드 제거/이름 변경
  • 인증 방식 변경
  • 오류 코드 체계 변경

Breaking Change가 아닌 것​

  • 선택적 파라미터 추가
  • 응답에 새 필드 추가
  • 버그 수정
  • 성능 개선

API 버전별 문서​

각 버전의 전체 문서:

버전문서 URL상태
v1/reference/api/현재
v2/reference/api-v2/준비 중

관련 문서​