호환성 파괴 변경 정책

개요

빠른 개발과 안정성 유지를 균형 있게 달성하기 위해 ElevenLabs는 API 범위에서 호환성 파괴 변경으로 간주되는 사항에 관한 구체적인 지침을 마련했습니다. 여기에서는 호환성 파괴 변경으로 간주하는 사항과 그렇지 않은 사항을 설명합니다.

응답 및 스키마 변경

API 응답의 추가 변경과 제거 변경을 명확히 구분합니다. 응답 모델에 새 필드를 추가하는 것은 호환성 파괴 변경으로 간주하지 않습니다. API를 통합할 때는 API 클라이언트가 인식하지 못하는 필드를 무시하고 API 응답에 대해 엄격한 타입 검사를 하지 않아야 합니다. 대부분의 최신 API 클라이언트는 기본적으로 이를 지원합니다.

기존 응답 필드를 제거하거나 구조를 수정하는 것은 클라이언트 애플리케이션이 이러한 필드의 존재와 예상 형식 유지를 전제로 할 수 있으므로 호환성 파괴 변경입니다.

매개변수 수정

API 매개변수 변경에는 엄격한 호환성 모델이 적용됩니다. 기존 엔드포인트에 필수 매개변수를 추가하면 기존 클라이언트 호출이 유효성 검사를 통과하지 못하므로 항상 호환성 파괴 변경입니다. 반면 선택적 매개변수(기본값이 있거나 명시적으로 선택 사항으로 표시된 매개변수)를 추가하는 것은 기존 클라이언트 호출이 수정 없이 계속 작동할 수 있으므로 호환성 파괴 변경이 아닙니다. 마찬가지로 매개변수 타입이나 형식을 변경하거나 기존 선택적 매개변수를 필수로 만드는 것은 클라이언트가 기대하는 계약을 변경하므로 호환성 파괴 변경으로 간주됩니다.

엔드포인트 및 경로 변경

전체 엔드포인트나 API 경로를 제거하면 해당 엔드포인트를 호출하는 클라이언트 애플리케이션에서 오류가 발생하므로 본질적으로 호환성 파괴 변경입니다. 엔드포인트는 지원 종료로 표시될 수 있지만, 영향을 받는 모든 사용자에게 충분히 안내하기 전에는 완전히 제거하지 않습니다.