v1이고, 아직 안정화 전인 일부는 v1beta입니다.
v1과 v1beta
v1의 하위 호환성
v1 경로에서는 기존 클라이언트가 계속 동작하도록 유지합니다. 다음 변경은 호환되는 변경으로 보고 예고 없이 반영합니다.
- 응답에 새 필드 추가
- 선택 요청 파라미터 추가
- 새 엔드포인트 추가
- 모델 ID, 실행 상태, 오류
code처럼 값 목록이 정해진 필드에 새 값 추가
v1 경로에 적용하지 않습니다. 필요하면 새 버전 경로로 제공합니다. 모든 변경은 Changelog에 기록됩니다.
v1beta 사용 시 주의
프로덕션에서 beta 엔드포인트에 의존한다면 다음을 권장합니다.- 호출부를 한곳에 모아 두세요. 경로나 응답이 바뀔 때 고칠 범위가 줄어듭니다.
- 응답을 그대로 저장하기보다 필요한 값만 추출해 자체 스키마로 저장하세요.
- Changelog를 구독하세요. RSS를 제공합니다.
v1으로 승격되면 Changelog에 공지합니다.
호출하는 엔드포인트의 버전 확인
요청 경로에/v1beta/가 들어 있으면 beta입니다. 각 API Reference 페이지 상단에 실제 경로가 적혀 있으니 거기서 확인하세요.
버전은 리소스 단위로 올라갑니다. 같은 데이터를 다루더라도 답변
조회(
/v1/platform/answers)와 인용 출처
통계(/v1beta/platform/sources/statistics/domains)처럼 버전이 다를 수
있습니다.변경에 강한 클라이언트
- 모르는 필드는 무시하세요. 응답에 새 필드가 추가돼도 파싱이 실패하면 안 됩니다. 알 수 없는 키에서 오류를 내는 엄격한 역직렬화 설정을 끄세요.
- 필드가 항상 있다고 가정하지 마세요.
include파라미터로 요청했는지, 데이터가 있는지에 따라 응답에서 빠질 수 있습니다. - 모르는 값에 대비하세요. 모델 ID, 실행
status, 오류code는 새 값이 추가될 수 있습니다. 분기문에 기본 처리를 두세요. - 버전 경로를 상수로 분리하세요.
/api/v1/platform을 코드 곳곳에 하드코딩하지 않으면 승격 시 한 곳만 고치면 됩니다.