대부분의 애플리케이션은 클라이언트 SDK의 형태나 API URL을 사용하여 작성됩니다. 클라이언트 SDK 및 API URL은 특정 Looker API 버전에 바인딩됩니다. Looker가 새 API 버전을 변경하더라도 애플리케이션은 계속 작동합니다. 클라이언트 SDK를 업그레이드 (또는 API URL을 수정)하여 새 Looker API 버전을 사용하도록 선택해야 애플리케이션이 다른 API 버전의 변경사항의 영향을 받습니다.
Looker에서 API를 변경하는 방법
Looker API는 Looker API 엔드포인트에 안정성을 제공하도록 설계되어 애플리케이션 안정성을 제공합니다.
Looker에 더 많은 기능을 추가할 뿐만 아니라 새로운 기능에 액세스하거나 이를 관리할 수 있도록 Looker REST API도 업데이트합니다. 각 Looker 출시에 대해 현재 버전의 Looker API에 새로운 API 함수, 매개변수, 응답 유형 속성을 추가합니다. 대부분의 경우 API에 추가되는 것은 브레이킹 체인지가 아니므로, API에 빌드된 기존 애플리케이션 코드에 영향을 주지 않고 API의 기존 버전을 유지할 수 있습니다. 기존 애플리케이션 코드는 후속 Looker 출시 버전에 표시되는 새로운 함수, 매개변수, 기능을 인식하지 못할 수 있습니다.
기존 애플리케이션 코드를 손상시키는 API 변경사항의 경우 이러한 브레이킹 체인지를 새 API 버전에 번들로 제공합니다. 즉, 이전 API 버전은 이전과 동일하게 작동하지만 새 API 버전은 변경사항 및 업데이트와 함께 실행됩니다. 단일 Looker 인스턴스에 여러 API 버전이 나란히 존재할 수 있으므로 새 API 버전으로 업그레이드할 시기를 선택할 수 있습니다. 이전 엔드포인트를 호출하도록 만들어진 기존 코드는 이전 엔드포인트를 계속 호출합니다. 새 코드는 최신 API 버전 수준에서 새 버전의 엔드포인트를 호출해야 합니다.
중요한 보안 문제는 예외입니다. Google은 API의 특정 부분과 관련된 심각한 보안 문제를 발견하는 경우 해당 보안 문제를 최대한 빨리 완화하기 위해 필요한 조치를 취할 것입니다.
더 나은 구현 또는 솔루션을 위해 기능, 함수 또는 속성을 사용 중지해야 하는 경우 일반적으로 현재 API는 그대로 두지만 연결된 API 엔드포인트를 '지원 중단됨'으로 표시하여 애플리케이션 코드의 엔드포인트에서 나가야 함을 나타냅니다.
API에 관한 브레이킹 체인지 및 추가 변경사항
브레이킹 변경사항은 API 엔드포인트의 기존 아티팩트를 삭제하거나 이름을 변경하는 것입니다. 여기에는 다음이 포함될 수 있습니다.
- 매개변수 이름 또는 유형 변경 또는 삭제
- 새 필수 매개변수 추가
- 기본 URL 변경
- 응답에서 기존 속성 변경 또는 삭제
반면에 추가 변경사항은 안정적인 엔드포인트에 적용될 수 있습니다. 여기에는 다음이 포함될 수 있습니다.
- 새로운 선택적 매개변수
- 응답의 새 속성 (REST API 커뮤니티에서 흔히 볼 수 있는 방식인 응답에서 알 수 없는 속성을 무시한다고 가정하므로 이 깨짐으로 간주하지 않음)
안정적인 Looker API 엔드포인트를 사용하는 데 새로운 아키텍처 또는 기능이 필요한 경우, 일반적으로 새 엔드포인트에 변경사항이 추가되고 새 API 버전에 번들로 제공되어 기존 API 엔드포인트는 변경되지 않습니다.
API 엔드포인트용 플래그
대부분의 API 엔드포인트는 안정화되는 것으로 간주되며, 즉 변경되지 않습니다. 보안 문제 해결과 같은 극단적인 경우를 제외하고 Looker는 안정적인 엔드포인트에 브레이킹 체인지를 적용하지 않습니다.
다른 API 엔드포인트는 beta 또는 Deprecated로 신고될 수 있습니다.
- 베타 엔드포인트는 현재 개발 중이며 향후 변경될 수 있습니다. 브레이킹 체인지로부터 보호되지 않습니다. 베타 엔드포인트를 사용할 때 Looker API의 변경사항이 앱이나 개발 주기에 특히 방해가 되는지 고려하세요. 변경사항이 있는지 알 수 있도록 베타 엔드포인트를 사용하려면 Looker의 출시 노트를 확인하세요.
- 지원 중단된 엔드포인트는 계속 지원되며 현재 계속 사용할 수 있지만 향후 출시 버전에서 삭제될 예정입니다. 지원 중단된 엔드포인트를 사용하는 이전 코드는 지원 중단된 엔드포인트 사용을 중지해야 합니다. 향후 Looker 버전에서 해당 엔드포인트에 대한 지원을 삭제하면 이 엔드포인트를 아직 사용하는 코드가 모두 중단됩니다. 대부분의 경우 지원 중단된 엔드포인트가 향상된 기능으로 대체됩니다. 애플리케이션에서 지원 중단된 함수나 속성을 사용하고 있다면 최대한 빨리 지원 중단된 요소를 대체하도록 코드를 리팩터링하는 것이 좋습니다.
베타 및 지원 중단된 엔드포인트는 API 참조에 다음과 같이 표시됩니다. 표시되지 않은 엔드포인트는 안정적인 것으로 간주됩니다.
새 API 버전으로 마이그레이션
클라이언트 SDK 또는 API URL을 새 API 버전으로 업그레이드할 경우 애플리케이션 코드를 검토하여 새 API 버전에서 변경된 사항을 사용하고 있는지 확인해야 합니다. 다음 단계를 따르세요.
- 애플리케이션 코드에서 업데이트된 함수, 값, 속성 이름을 검색합니다.
- 애플리케이션 코드가 유형 변경 (예: 정수에서 문자열로)을 지원하는지 확인합니다.
- 코드를 감사합니다 (아래 섹션 참고).
코드 감사
일부 언어에서는 빌드 시간에 API의 브레이킹 체인지를 컴파일 오류로 탐색할 수 있습니다.
- 애플리케이션이 강력하게 형식이 지정된 언어로 작성되는 경우 기존 유형과 상충하는 새 API 버전의 매개변수 또는 응답 유형에 대한 구조적 변경사항은 컴파일 유형 확인 및 컴파일러 오류 메시지를 통해 쉽게 알아볼 수 있습니다.
- 애플리케이션이 느슨하게 유형이 지정된 동적 언어 (예: 자바스크립트, Ruby, Python)로 작성된 경우 새 API 버전의 변경사항으로 인해 영향을 받게 될 애플리케이션 부분을 찾기가 더 어려울 수 있습니다. 이러한 유형의 언어는 유형 변경과 관련된 문제를 찾기 위해 런타임 단위 테스트가 필요할 수 있습니다.
모든 경우에 모의 호출이 아닌 Looker API 호출을 포함하여 애플리케이션 코드를 실행하는 단위 테스트를 수행하는 것이 가장 좋습니다.