API 버전 관리

세 가지 주요 접근 방식이 있습니다. URI 버전 관리(/v1/, /v2/)가 가장 일반적입니다. 클라이언트는 모든 요청 URL에 버전을 명시적으로 지정합니다. 간단하고 가시성이 높지만, 팀이 병렬로 유지해야 하는 경로는 각 주요 버전마다 증가합니다. 헤더 버전 관리(API-Version: 2024-01-01)는 URL을 깔끔하게 유지하고 날짜 기반 버전 관리(Stripe 모델)를 허용합니다. 이 모델에서는 각 API 버전이 날짜로 명명되며 고객은 계정 기념일에 새로운 기본값으로 업그레이드됩니다. 쿼리 파라미터 버전 관리(?version=2)는 가장 간단하지만 종종 가장 깔끔하지 않다고 여겨집니다. 대부분의 SaaS API는 공개 API에 URI 버전 관리를 사용합니다. 메커니즘과 관계없이 고객에게 약속해야 할 핵심 사항은 다음과 같습니다. 이전 버전은 얼마나 오랫동안 지원될까요? (업계 표준은 새 버전 출시 후 12~24개월입니다); 호환성을 깨는 변경 사항은 어떻게 정의되고 전달될까요? ("호환성을 깨는 변경 사항"에 대한 공식적인 정의는 사용 중단 시 논쟁을 방지합니다); 그리고 마이그레이션 경로는 무엇인가요? (코드 예제가 포함된 명확한 마이그레이션 가이드를 제공합니다).

API 사용 중단은 고객 신뢰와 관련된 이벤트입니다. 제대로 처리되지 않으면, 근본적인 제품 개선이 긍정적일지라도 상당한 부정적인 감정을 유발합니다. SaaS API 사용 중단을 위한 모범 사례: 12개월 이상 전에 사용 중단을 발표합니다(사용량이 적은 엔드포인트의 경우 최소 6개월); 구체적인 종료 날짜를 제공합니다(모호한 사용 중단 일정은 잘못된 안정감을 조성합니다); 사용 중단된 엔드포인트를 활발히 사용하는 모든 고객에게 타겟 알림을 보냅니다(API 로그에서 식별 가능 — "[회사명]님께, 저희 기록에 따르면 /v1/users를 호출하고 계십니다. 이 엔드포인트는 [날짜]에 종료됩니다. 마이그레이션 방법은 다음과 같습니다:"); 이전/이후 코드 예제가 포함된 상세 마이그레이션 가이드를 게시합니다; 새 버전이 이전 스키마에서 변환되는 호환성 모드 또는 시밍 기간을 제공합니다; 그리고 고객이 관리 설정에서 볼 수 있는 사용 중단된 엔드포인트 사용 대시보드를 생성하여 사용량과 남은 시간을 표시합니다.

API 사용 중단은 확실히 지원 티켓 급증을 유발합니다. 고객은 마지막 순간에 마이그레이션하고, 통합 문제가 발생하며, 일부 고객은 사용 중단 사실을 완전히 놓치기도 합니다. 완화 전략: 한 번에 모두 종료하는 대신 단계적으로 종료합니다(전체 종료 2주 전에 영향을 받는 고객 중 무작위로 5%에 대해 비활성화하여 전체 영향이 발생하기 전에 관리 가능한 수준의 문제가 발생하도록 합니다); 사용 중단 기간 동안 지원 인력을 충원합니다(종료 날짜 전후 2주 동안 추가 상담원 시간을 배정합니다); 마이그레이션 가이드와 일반적인 오류 해결책이 포함된 Zendesk 매크로를 미리 구축하여 Tier 1 상담원이 엔지니어링 에스컬레이션 없이 신속하게 첫 접점 해결을 할 수 있도록 합니다; 전담 "API 마이그레이션" Zendesk 뷰를 생성하여 이러한 티켓이 가장 기술적으로 유능한 상담원에 의해 분류되도록 합니다; 그리고 종료 당일 개발자 상태 페이지에 실시간 상태 업데이트를 게시하고, 마이그레이션 관련 오류 급증을 모니터링합니다.