안정성 정책
API 응답에 필드나 열거형 값이 추가되어도 연동 기능이 계속 동작하도록 아래 처리 방법을 적용합니다.
1. 하위 호환성 변경 원칙
섹션 제목: “1. 하위 호환성 변경 원칙”| 변경 구분 | 변경 유형 및 세부 내용 | 사전 공지 및 적용 방식 |
|---|---|---|
| 호환성 유지 변경 (Non-Breaking) |
- 기존 응답 JSON에 신규 속성/필드 추가 - 신규 리소스 엔드포인트 추가 - 새로운 열거형(Enum) 값 추가 - 에러 message 안내 문구 개선 |
필드·열거형 값이 추가되면 아래 클라이언트 처리 규칙을 적용합니다. |
| 호환성 파괴 변경 (Breaking) |
- 기존 필드 제거 또는 이름 변경 - 기존 필드의 데이터 타입 변경 (예: string → number) - 엔드포인트 URL 경로 변경 - 필드의 비즈니스 의미(Semantics) 변경 |
체인지로그 및 이메일로 사전 공지한 뒤 유예 기간을 거쳐 적용합니다. |
2. 응답 변경에 대응하기
섹션 제목: “2. 응답 변경에 대응하기”API가 업데이트되어도 시스템 중단 없이 안정적으로 동작하도록 다음 수칙에 따라 클라이언트를 구현합니다.
- 새 필드는 무시하도록 설정합니다. 예를 들어 Jackson은
FAIL_ON_UNKNOWN_PROPERTIES = false로 설정합니다. code를 기준으로 예외 처리를 분기하고message는 사용자 안내에 사용합니다.- 처음 보는 캠페인 상태나 통화 코드를 처리할
default분기를 구현합니다.
3. Core API 변경 이력
섹션 제목: “3. Core API 변경 이력”체인지로그에서 API 변경 이력을 확인합니다.
다음 단계
섹션 제목: “다음 단계”- API 개요 및 시작하기: Core API의 기본 통신 규약과 첫 호출 가이드를 확인합니다.
- 전체 체인지로그: EasterAd 플랫폼 전체의 정책 및 시스템 변경 기록을 확인합니다.