대부분의 애플리케이션은 어떤 형태로든 클라이언트 SDK 또는 API URL을 사용하여 작성됩니다. 클라이언트 SDK 및 API URL은 특정 Looker API 버전에 바인딩됩니다. Looker가 새 API 버전을 변경하더라도 애플리케이션은 계속 작동합니다. 새 Looker API 버전을 사용하도록 클라이언트 SDK를 업그레이드하거나 API URL을 수정하기 전에는 애플리케이션이 다른 API 버전의 변경사항에 영향을 받지 않습니다.
Looker에 더 많은 기능을 추가할수록 Looker REST API도 업데이트하여 이러한 새 기능에 액세스하거나 이를 관리할 수 있습니다. 각 Looker 출시 버전의 경우 Looker API의 현재 버전에 새로운 API 함수, 매개변수, 응답 유형 속성이 추가됩니다. 대부분의 경우 API에 추가해도 브레이킹 체인지가 되지 않으므로 API를 기반으로 개발된 기존 애플리케이션 코드에 영향을 주지 않고 API의 기존 버전을 유지할 수 있습니다. 기존 애플리케이션 코드는 단순히 Looker 출시 버전에 나타나는 새로운 함수, 매개변수 또는 기능을 인식하지 못할 수도 있습니다.
기존 애플리케이션 코드가 중단될 수 있는 API 변경사항의 경우 이러한 브레이킹 체인지를 새 API 버전과 번들로 구성합니다. 즉, 이전 API 버전은 이전과 동일하게 계속 작동하지만 새 API 버전은 변경사항 및 업데이트와 함께 실행됩니다. 단일 Looker 인스턴스에 여러 API 버전이 나란히 존재할 수 있으므로 새 API 버전으로 업그레이드할 시기를 선택할 수 있습니다. 이전 엔드포인트를 호출하도록 빌드된 기존 코드는 계속해서 이전 엔드포인트를 호출합니다. 새 코드는 최신 API 버전 수준에서 새 버전의 엔드포인트를 호출해야 합니다.
중요한 보안 문제에 대해서는 예외입니다. API의 특정 부분과 관련된 심각한 보안 문제가 발견되면 Google은 적절한 해결책이 제공될 때까지 취약한 기능을 사용 중지하는 등 해당 보안 문제를 최대한 빨리 완화하기 위해 필요한 조치를 모두 취합니다.
더 나은 구현이나 솔루션을 위해 기능, 함수 또는 속성을 사용 중지해야 하는 경우 일반적으로 현재 API를 그대로 두지만, 애플리케이션 코드의 엔드포인트에서 벗어나야 함을 나타내기 위하여 연결된 API 엔드포인트를 '지원 중단됨'으로 표시합니다.
API에 대한 브레이킹 체인지 및 추가 변경사항
브레이킹 체인지는 API 엔드포인트의 기존 아티팩트를 삭제하거나 이름을 바꾸는 것입니다. 여기에는 다음이 포함될 수 있습니다.
매개변수 이름이나 유형의 변경 또는 삭제
새 필수 매개변수 추가
기준 URL 변경
응답에서 기존 속성 변경 또는 삭제
반면에 추가 변경이 안정적인 엔드포인트에 적용될 수 있습니다. 여기에는 다음이 포함될 수 있습니다.
새로운 선택적 매개변수
응답의 새 속성(코드에서 REST API 커뮤니티에서 일반적으로 사용되는 알 수 없는 속성을 무시한다고 가정하기 때문에 호환성이 손상되는 것은 고려되지 않음)
안정적인 Looker API 엔드포인트에 새 아키텍처나 기능을 도입하기 위해 상당한 변경이 필요한 경우 변경사항은 일반적으로 새 엔드포인트에 추가되고 기존 API 엔드포인트가 변경되지 않도록 새 API 버전에 번들로 포함됩니다.
API 엔드포인트의 플래그
대부분의 API 엔드포인트는 안정적인 것으로 간주되며, 이는 변경되지 않을 것으로 예상된다는 의미입니다. Looker는 보안 문제 해결과 같은 극단적인 경우를 제외하고 안정적인 엔드포인트에 브레이킹 체인지를 적용하지 않습니다.
다른 API 엔드포인트는 베타 또는 지원 중단으로 표시될 수 있습니다.
베타 엔드포인트는 현재 개발 중이며 향후 변경될 수 있습니다. 브레이킹 체인지로부터 보호되지 않습니다. 베타 엔드포인트를 사용할 때 Looker API로 인해 변경사항이 앱 또는 개발 주기에 특히 지장을 주는지 여부를 고려하세요. 변경 사항을 확인할 수 있도록 베타 엔드포인트를 사용하려면 Looker의 출시 노트를 읽어보시기 바랍니다.
지원 중단된 엔드포인트는 여전히 지원되고 현재 계속 사용할 수 있지만 향후 출시 버전에서 삭제될 예정인 엔드포인트입니다. 지원 중단된 엔드포인트를 사용하는 이전 코드는 지원 중단된 엔드포인트의 사용을 중지하도록 업데이트해야 합니다. 향후 Looker 출시 버전에서 이 엔드포인트 지원이 중단되면 이 엔드포인트를 계속 사용하는 모든 코드가 중단됩니다. 대부분의 경우 지원 중단된 엔드포인트는 개선된 기능으로 대체됩니다. 애플리케이션에서 지원 중단된 함수나 속성을 사용하는 경우 가능한 한 빨리 지원 중단된 요소를 대체하도록 코드를 리팩터링하는 것이 좋습니다.
베타 및 지원 중단된 엔드포인트는 API 탐색기 및 4.0 API 참조에서 이렇게 표시됩니다. 표시되지 않은 엔드포인트는 안정적인 것으로 간주됩니다.
새 API 버전으로 이전
클라이언트 SDK 또는 API URL을 새 API 버전으로 업그레이드하려면 애플리케이션 코드를 검토하여 새 API 버전에서 변경된 항목을 사용하고 있는지 확인해야 합니다. 다음 조치를 취해야 합니다.
일부 언어의 경우 빌드 시간에 컴파일 오류로 API의 브레이킹 체인지를 발견할 수 있습니다.
강력하게 형식이 지정된 언어로 애플리케이션이 작성되는 경우, 기존 코드와 상충하는 새 API 버전의 매개변수 또는 응답 유형의 구조적 변경사항은 컴파일 유형 확인 및 컴파일러 오류 메시지 덕분에 명확히 드러나게 됩니다.
유형이 느슨하게 지정된 동적 언어(예: 자바스크립트, Ruby, Python)로 애플리케이션이 작성된 경우 새 API 버전에서 브레이킹 체인지의 영향을 받는 애플리케이션 부분을 찾기가 더 어려울 수 있습니다. 이러한 유형의 언어는 유형 변경과 관련된 문제를 찾기 위해 런타임 단위 테스트가 필요할 수 있습니다.
모든 경우에 가장 좋은 방법은 Looker API(모의 호출이 아님) 호출을 포함하여 애플리케이션 코드를 실행하는 단위 테스트를 하는 것입니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-07-31(UTC)"],[],[],null,["# Looker API versioning\n\n| **Note:** As of Looker 22.4, the [Looker API 4.0 is generally available](/looker/docs/api-4-ga). In Looker 23.18, the [Looker API 3.1 has been removed](/looker/docs/api-3x-deprecation).\n\nMost applications are written using some form of a client SDK, or possibly an API URL. The client SDK and API URLs are bound to a specific Looker API version. Your application will continue to function even as Looker makes changes to new API versions. Your application won't be affected by changes in other API versions until you choose to upgrade your client SDK (or modify the API URL) to use the new Looker API version.\n\nHow Looker makes changes to the API\n-----------------------------------\n\nThe Looker API is architected to provide stability for Looker API endpoints, and therefore stability for your applications.\n\nAs we add more features and capabilities to Looker, we also update the Looker REST API to access or manage those new features. For each Looker release, we add new API functions, parameters, and response type properties to the current version of the Looker API. In most cases, additions to the API are not [breaking changes](#breaking_and_additive_changes), so we can keep the existing version of the API without affecting any existing application code that is built on the API. Your existing application code may simply be unaware of new functions, parameters, or features that appear in subsequent Looker releases.\n\nFor changes to the API that would break existing application code, we bundle those breaking changes into a new API version. This means that the old API version will continue to work the same as before, while a new API version runs alongside it with the changes and updates. Multiple API versions can exist side by side in a single Looker instance so that you can choose when to upgrade to the new API version. Your existing code that was built to call the old endpoint will continue to call the old endpoint. New code should call the new version of the endpoint in the most recent API version level.\n\nOne exception to this is for critical security issues. If we discover a critical security issue related to a particular part of the API, we will do whatever is necessary to mitigate that security issue as soon as possible, which may include disabling the vulnerable functionality until a proper solution is available).\n\nIf we need to retire a feature, function, or property to make way for a better implementation or solution, we normally leave the current API as it is, but mark the associated API endpoints as [\"deprecated\"](/looker/docs/api-versioning#deprecated_api_endpoints) to indicate that you should move away from the endpoint in your application code.\n\n### Breaking and additive changes to the API\n\nA *breaking* change is something that deletes or renames an existing artifact of an API endpoint. It might include:\n\n- Changing or deleting a parameter name or type\n- Adding a new required parameter\n- Changing the base URL\n- Changing or deleting an existing property in a response\n\nAn *additive* change, on the other hand, may be made to [stable](#stable_api_endpoints) endpoints. They might include:\n\n- New, optional parameters\n- New properties in responses (we do not consider this breaking because we assume that your code will ignore unknown properties in responses, which is common practice in the REST API community)\n\nIf a stable Looker API endpoint needs a significant change to move forward with new architecture or functionality, the change is usually added to a new endpoint and bundled into a new API version so that the existing API endpoint remains unchanged.\n\n\nFlags for API endpoints\n-----------------------\n\nMost API endpoints are considered *stable* , meaning they are not expected to change. Looker will not release [breaking changes](#breaking_and_additive_changes) to stable endpoints except in extreme cases, such as to fix a security problem.\n\nOther API endpoints may be flagged as *beta* or *deprecated*:\n\n- **Beta endpoints** are in active development and may change in the future. They are not protected from breaking changes. When using beta endpoints, consider whether a change to the Looker API would be particularly disruptive to your app or development cycle. Please read Looker's [release notes](https://discourse.looker.com/search?q=%23news%3Arelease%20order%3Alatest) if you plan to use a beta endpoint so that you will be aware of any changes.\n- **Deprecated endpoints** are endpoints that are still supported and can still be used at the moment, but will be deleted in a future release. Old code that uses a deprecated endpoint should be updated to stop using the deprecated endpoint. When a future release of Looker removes support for that endpoint, any code that is still using it will break. In most cases, a deprecated endpoint will be replaced by improved functionality. If you find that your application is using a deprecated function or property, it's a good idea to refactor your code to replace the deprecated element as soon as you can.\n\nBeta and deprecated endpoints are marked as such in the [API Explorer](/looker/docs/api-explorer) and in the [4.0 API Reference](/looker/docs/reference/looker-api/latest). Endpoints that aren't marked are considered stable.\n\n\nMigrating to a new API version\n------------------------------\n\nWhen you choose to upgrade your client SDK or API URL to a new API version, you will need to review your application code to see if you're relying on something that has changed with the new API version. Be sure to do the following:\n\n1. Search your application code for the updated function, value, and property names.\n2. Verify that your application code supports any changes in types (such as integer to string).\n3. Audit your code (see the [Auditing your code section](#auditing_your_code)).\n\n### Auditing your code\n\nFor some languages, breaking changes in the API can be discovered at build time as compile errors:\n\n- If your application is written in a compiled, strongly-typed language, structural changes to parameter or response types in a new API version that are at odds with your existing code should be readily apparent thanks to compile type checking and compiler error messages.\n- If your application is written in a loosely-typed dynamic language (such as JavaScript, Ruby, and Python), it may be harder to locate the parts of your application that will be affected by breaking changes in a new API version. These types of languages might require runtime unit tests to find any issues related to changes in types.\n\nIn all cases, the best practice is to have unit tests that exercise your application code, including calls to the Looker API (not mocked calls)."]]
