API 버전과 수명주기

Foundry API는 Semantic Versioning의 주 버전(major version)만 URL에 표시합니다. 예를 들어 V2 엔드포인트는 다음 형태입니다.

https://<hostname>/api/v2/...

새 주 버전이 필요한 변경

기존 클라이언트와 호환되지 않는 다음 변경에는 v1에서 v2로의 이동처럼 새 버전 번호가 필요합니다.

• 엔드포인트 또는 필드 제거
• 새로운 필수 요청 매개변수 추가
• 응답 필드 제거 또는 기존 필드 자료형 변경

같은 주 버전 안의 변경

다음 변경은 호환성을 유지하는 변경으로 처리하며 버전 번호를 바꾸지 않고 배포할 수 있습니다.

• 선택적 요청 매개변수 추가
• 필수 요청 매개변수를 선택 항목으로 변경
• 응답 필드, 열거형 값 또는 엔드포인트 추가
• 기능을 바꾸지 않는 성능 개선과 오류 수정

클라이언트는 모르는 응답 필드를 무시하고 새로운 열거형 값에 대응할 기본 처리를 마련해야 합니다. 명시되지 않은 내부 구현이나 동작에 의존하지 않습니다. 이전 버전의 엔드포인트도 사용 중단 대상이 되지 않았다면 계속 사용할 수 있습니다.

사용 중단 예고와 이전

기반 기능을 더 이상 제공하지 않는 등의 이유로 안정 엔드포인트나 이전 버전을 대체하거나 제거할 수 있습니다. 안정 엔드포인트의 변경은 원칙적으로 최소 12개월 전에 알리며 그동안 지원과 SLA를 유지합니다.

알림은 공개 공지, Upgrade Assistant의 이메일 및 플랫폼 내 알림, 해당 엔드포인트의 사용 중단 안내로 전달합니다. 이전을 위해 구버전과 새 버전의 구조 비교, 코드 변경 예시, 일반적인 이전 패턴, 플랫폼 지원 채널과 Developer Community의 안내를 제공합니다.

심각한 보안 취약점이나 시스템 안정성 문제에 즉시 대응해야 하는 예외적인 경우에는 더 짧은 사전 통지로 호환성을 깨는 변경이 이루어질 수 있습니다.

공개 프리뷰

공개 프리뷰(Public Preview)는 개발 중인 엔드포인트를 비운영 목적으로 제공하는 단계입니다. 요청에 preview=true 쿼리 매개변수를 넣어 사용에 동의해야 합니다.

?preview=true

공개 프리뷰 엔드포인트는 사전 통지 없이 변경되거나 제거될 수 있습니다. 안정 엔드포인트의 12개월 사전 안내를 프리뷰에도 적용한다고 가정하지 않습니다. 해당 엔드포인트에 표시된 프리뷰 경고와 개별 제약을 확인합니다.