버전 관리와 사용 중단

API 버전 관리, 변경 사항 배포, 호환성을 깨는 변경이나 제거에 대한 사전 안내 방식을 설명합니다.

API와 SDK 버전

REST API 버전은 경로의 /v1에 표시됩니다. 버전 헤더는 없습니다. /mcp의 MCP는 자체 프로토콜 버전을 협상합니다.

SDK 패키지 버전은 API 버전과 별개입니다.

/v1 내에서 엔드포인트와 MCP 도구, 데이터 세트, 국가나 제공 범위, 기존 동작을 유지하는 선택적 입력을 추가할 수 있습니다. 이러한 변경은 사전 안내 없이 언제든 배포할 수 있습니다.

선택적이거나 null을 허용하는 응답 필드와 응답 열거형의 새 값도 사전 안내 없이 추가할 수 있습니다. 이러한 변경은 변경 이력에 기록합니다.

클라이언트는 알 수 없는 필드를 무시하고 알 수 없는 열거형 값도 허용해야 합니다. 당사 SDK는 이미 이 방식으로 동작합니다.

필드를 제거하거나 이름을 바꾸는 것은 호환성을 깨는 변경입니다. 필드의 타입, 의미, 단위, 정밀도 또는 필수 여부를 바꾸는 것도 마찬가지입니다.

경로나 메서드, 인증, 권한 부여, 할당량 또는 기본 동작을 바꾸는 것도 호환성을 깨는 변경입니다.

호환성을 깨는 변경은 새 경로나 작업 또는 새 메이저 버전으로 배포합니다. 기존 경로나 작업 또는 버전을 알리지 않고 변경하지 않습니다.

호환성을 깨는 변경이나 제거가 최근 90일 동안 계정에서 호출한 엔드포인트나 필드에 영향을 주는 경우, 적용일 최소 3개월 전에 안내합니다. 이메일과 변경 이력으로 안내합니다.

최근 90일 동안 어떤 계정에서도 호출하지 않은 엔드포인트나 필드는 더 짧은 사전 안내 기간을 두고 제거할 수 있습니다. 이러한 제거는 변경 이력에 공지합니다.

변경 사항은 변경 이력과 해당 RSS 피드에 공지합니다.

경제 이벤트의 event_type 필드는 type의 별칭이며 사용 중단이 권고됩니다. type을 사용하세요.

제거 날짜는 정해지지 않았습니다. 날짜를 정할 때는 위의 사전 안내 정책을 따릅니다.