안정성 정책

EasterAd Core API는 URL에 /v1, /v2와 같은 버전 접두사를 두지 않는 연속 배포(Continuous Evolution) 모델을 따릅니다. 이를 위해 엄격한 하위 호환성 보장 원칙을 적용하고 있으며, 클라이언트는 변경에 유연하게 대응할 수 있도록 방어적으로 설계되어야 합니다.

1. 하위 호환성 변경 원칙

EasterAd는 API 변경 사항을 호환성을 유지하는 변경(Additive Changes)과 호환성을 깨는 변경(Breaking Changes)으로 명확히 구분하여 운영합니다.

변경 구분	변경 유형 및 세부 내용	사전 공지 및 적용 방식
호환성 유지 변경 (Non-Breaking)	- 기존 응답 JSON에 신규 속성/필드 추가 - 신규 리소스 엔드포인트 추가 - 새로운 Enum 열거형 값 추가 - 에러 `message` 안내 문구 가독성 개선	사전 예고 없이 수시로 배포될 수 있습니다.
호환성 파괴 변경 (Breaking)	- 기존 필드 제거 또는 이름 변경 - 기존 필드의 데이터 타입 변경 (예: string → number) - 엔드포인트 URL 경로 변경 - 필드의 비즈니스 의미(Semantics) 변경	체인지로그 및 이메일을 통해 사전 공지 후 유예 기간을 거쳐 적용됩니다.

2. 방어적 클라이언트(Defensive Client) 개발 지침

API의 지속적인 업데이트에도 시스템 중단 없이 안정적으로 동작하는 클라이언트를 작성하기 위한 모범 수칙입니다.

알 수 없는 필드 무시 (Ignore Unknown Properties)
- JSON 역직렬화(Deserialization) 시 스키마에 정의되지 않은 신규 필드가 포함되어 있더라도 파서가 에러를 발생시키지 않도록 설정하세요. (예: Jackson의 FAIL_ON_UNKNOWN_PROPERTIES = false)
머신 코드 기반 분기
- 사용자 안내용 문구(message)는 다국어 번역이나 표현 개선으로 변경될 수 있습니다. 예외 처리 로직은 반드시 불변 식별자인 code 필드를 기준으로 작성하세요.
Enum 열거형 미지 값 처리 (Unknown Fallback)
- 향후 새로운 캠페인 상태나 통화 코드가 추가될 수 있습니다. Switch 문 등에서 처리되지 않은 Enum 값이 들어왔을 때 크래시가 나지 않도록 default 처리를 반드시 마련하세요.
기술 지원 문의 시 스펙 버전 명시
- API 동작과 관련하여 EasterAd 기술팀에 문의할 때는 대상 엔드포인트 레퍼런스 페이지 하단에 표기된 스펙 버전을 함께 전달해 주시면 신속한 지원이 가능합니다.

3. Core API 변경 이력

적용 일자	변경 유형	내용 요약
`2026-09-05`	최초 공개	EasterAd Core API v1 정식 공개 (조직, 지갑 잔액, 캠페인, SDK 키 관리)

다음 단계

API 개요 및 시작하기: Core API의 기본 통신 규약과 첫 호출 가이드를 확인합니다.
전체 체인지로그: EasterAd 플랫폼 전체의 정책 및 시스템 변경 기록을 확인합니다.