API 버저닝(Versioning) 전략

API의 생명주기를 안전하게 관리하고 하위 호환성을 보장하는 핵심 전략. 이미 서비스를 사용하는 클라이언트가 있는 상황에서 API 변경 시 발생할 수 있는 장애를 방지하고 점진적인 마이그레이션을 가능하게 함

API 버저닝이 필요한 이유

• 하위 호환성 유지: 새 버전 배포 시에도 이전 버전 사용 클라이언트가 정상 동작하도록 보장

• 점진적인 마이그레이션: 클라이언트가 각자 일정에 맞춰 새 API 버전으로 전환할 시간 확보

• 명확한 의사소통: Breaking Change를 버전을 통해 명확하게 전달

• 안정적인 서비스 운영: 신규 버전 배포가 기존 서비스에 미치는 영향 최소화

Django REST Framework 버저닝 스킴

기본 설정

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
    'DEFAULT_VERSION': 'v1',
    'ALLOWED_VERSIONS': ['v1', 'v2'],
}

주요 버저닝 방식

URL 경로 버저닝 (URLPathVersioning)

• URL 경로에 버전 정보 포함

• 요청 예시: GET /api/v1/users/, GET /api/v2/users/

• 가장 직관적이고 널리 사용

쿼리 파라미터 버저닝 (QueryParameterVersioning)

• URL 쿼리 파라미터로 버전 명시

• 요청 예시: GET /api/users/?version=1.0

• URL 구조 변경 불필요

Accept 헤더 버저닝 (AcceptHeaderVersioning)

• HTTP Accept 헤더를 통해 버전 지정

• RESTful 원칙에 가장 부합

• 예시: Accept: application/json; version=1.0

버저닝 전략 선택 가이드

전략	장점	단점	사용 사례
URL 경로	명확하고 직관적, 테스트 용이, 캐싱 유리	URL 길어짐	공개 API, 일반적 사용
쿼리 파라미터	URL 구조 유지, 구현 간단	URL 지저분, 캐싱 복잡	내부 API, 프로토타이핑
Accept 헤더	URL 깔끔, RESTful 원칙 준수	테스트 어려움, 인지 어려움	엄격한 RESTful API

버전별 로직 처리

# serializers.py
class UserV1Serializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ['id', 'email', 'username']

class UserV2Serializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ['id', 'email', 'username', 'nickname']

# views.py
class UserListView(generics.ListAPIView):
    queryset = User.objects.all()
    
    def get_serializer_class(self):
        if self.request.version == 'v2':
            return UserV2Serializer
        return UserV1Serializer

API 버전 폐기 전략

1. 사전 공지: API 문서를 통해 폐기 일정 명시

2. Warning 헤더: 폐기 예정 API 호출 시 경고 메시지 전송

3. 모니터링: 폐기 예정 버전의 호출량 지속 추적

4. 최종 폐기: 약속된 시점에 API 제거 또는 에러 응답 반환