API 안정성 및 버전 관리
RealityConnect API를 장기적으로 활용하기 전에, 어떤 부분이 안정적인지, 실험적 작업은 어떻게 표시되는지, 업그레이드할 때마다 무엇을 확인해야 하는지 알아두세요.
실험적 작업
섹션 제목: “실험적 작업”API 레퍼런스의 일부 작업에는 실험적 안정성 표시가 붙어 있습니다. OpenAPI 문서에서 작업에 x-scalar-stability: experimental이 있는지 확인하세요(렌더링된 API 레퍼런스에서는 안정성 배지로 표시됩니다). 이는 API와 자동으로 동기화되므로, 여기에 고정된 목록을 두기보다 그곳을 확인하는 것이 더 정확합니다.
실험적 작업은 실제로 호출 가능한 작업이며 비활성화되거나 미리보기 전용이 아닙니다. 다만 경로, 매개변수, 페이로드, 응답, 가용성이 API의 다른 부분과 동일한 안정성 보장 없이 변경될 수 있습니다. 실험적 작업을 다루는 방법은 실험적 엔드포인트를 참고하세요.
실험적 작업이 안정화되면 릴리스 노트에서 이를 안내합니다.
호환성이 깨지는 변경과 깨지지 않는 변경
섹션 제목: “호환성이 깨지는 변경과 깨지지 않는 변경”| 변경 | 호환성이 깨지는가? | 이유 |
|---|---|---|
| 새로운 선택적 요청 매개변수 | 아니오 | 기존 요청은 변경 없이 계속 작동함 |
| 새로운 응답 필드 | 아니오 | 알려진 필드만 읽는 기존 클라이언트는 영향받지 않음. 응답을 관대하게 파싱하고 알려지지 않은 필드는 무시할 것 |
| 기존 필드에 새로운 enum 값 추가 | 아니오 | enum 필드를 열린 집합으로 취급하고, 알려진 값을 모두 나열해 대조하기보다 알려지지 않은 값도 유연하게 처리할 것 |
| 기존 필드 제거 또는 이름 변경 | 예 | 해당 필드를 읽는 모든 클라이언트가 깨짐 |
| 기존 필드의 타입이나 의미 변경 | 예 | 이전 형태에 의존하는 모든 클라이언트가 깨짐 |
| 기존 작업에 필수 매개변수 추가 | 예 | 이를 보내지 않는 기존 요청이 깨짐 |
| 엔드포인트 경로 또는 HTTP 메서드 변경 | 예 | 기존 요청이 완전히 깨짐 |
| 실험적 작업의 계약 변경 | 아니오(의도된 것) | 실험적 작업은 안정성 계약에서 명시적으로 제외됨(위 참고) |