ほとんどのアプリケーションは、なんらかのクライアント SDK または API URL を使用して記述されています。クライアント SDK と API URL は、特定の Looker API バージョンにバインドされています。Looker が新しい API バージョンに変更を加えても、アプリケーションは引き続き機能します。新しい Looker API バージョンを使用するようにクライアント SDK をアップグレードする（または API URL を変更する）まで、アプリケーションは他の API バージョンの変更による影響を受けません。
Looker が API を変更する仕組み
Looker API は、Looker API エンドポイントの安定性を確保し、アプリケーションの安定性を維持するように設計されています。
Looker にはさらに機能が追加されるとともに、それらの新しい機能にアクセスして管理するための Looker REST API も更新されています。Looker リリースごとに、新しい API 関数、パラメータ、レスポンス タイプのプロパティを現在のバージョンの Looker API に追加します。ほとんどの場合、API への追加は互換性を損なう変更にはならないため、API を基に構築された既存のアプリケーション コードに影響を与えることなく、既存バージョンの API を使用できます。既存のアプリケーション コードは、後続の Looker リリースで出現する新しい関数、パラメータ、機能を認識しない場合があります。
既存のアプリケーション コードとの互換性がない変更を API に加える場合は、それらの変更を新しい API バージョンにバンドルします。つまり、古い API バージョンは以前と同じように動作し、それと並行して、変更や更新を伴う新しい API バージョンが実行されます。1 つの Looker インスタンス内に複数の API バージョンが並行して存在できるため、新しい API バージョンにアップグレードするタイミングを選択できます。古いエンドポイントを呼び出すようにビルドされた既存のコードは、引き続き古いエンドポイントを呼び出します。新しいコードでは、最新の API バージョン レベルでエンドポイントの新しいバージョンが呼び出されます。
ただし、重大なセキュリティ問題については例外となります。API の特定の部分に関する重大なセキュリティの問題が見つかった場合は、適切な解決策が利用可能になるまで脆弱性のある機能を無効にするなど、セキュリティの問題を可能な限り早く軽減するために必要な措置を講じます。
実装やソリューションを向上させるために機能、関数、プロパティを廃止する必要がある場合、通常は現在の API をそのままにしますが、アプリケーション コード内のエンドポイントから離れるべきであることを示すために、関連する API エンドポイントを「非推奨」としてマークします。
API に対する、互換性を損なう変更および付加的な変更
互換性を損なう変更は、API エンドポイントの既存のアーティファクトを削除または名前変更するものです。次のような変更が含まれます。
- パラメータ名またはパラメータ型の変更または削除
- 新しい必須パラメータの追加
- ベース URL の変更
- レスポンス内の既存のプロパティの変更または削除
一方、付加的な変更は、安定版のエンドポイントに行われます。次のような変更が含まれます。
- 新しいオプション パラメータ
- レスポンスの新しいプロパティ（レスポンスで不明なプロパティはコードによって無視されることが想定されるため、これは互換性を損なう変更とはみなされません。これは REST API コミュニティで一般的な方法です）
安定版の Looker API エンドポイントで新しいアーキテクチャや機能のために大幅な変更が必要な場合、既存の API エンドポイントが変更されないように、通常、変更は新しいエンドポイントに追加され、新しい API バージョンにバンドルされます。
API エンドポイントのフラグ
ほとんどの API エンドポイントは安定していると見なされるため、変更されることは想定されていません。Looker は、セキュリティ問題を解決するためなどの極端な場合を除き、安定したエンドポイントに対して互換性を損なう変更をリリースしません。
その他の API エンドポイントには、ベータ版または非推奨のフラグが付けられます。
- ベータ版エンドポイントは現在開発中であり、今後変更される可能性があります。互換性を破る変更から保護されることはありません。ベータ版エンドポイントを使用する場合、Looker API への変更がアプリや開発サイクルを特に妨げるかどうかを考慮してください。ベータ版エンドポイントを使用する予定がある場合は、変更を認識できるように、Looker のリリースノートをご覧ください。
- 非推奨エンドポイントは、現時点ではまだサポートされており使用できますが、今後のリリースで削除される予定があるエンドポイントです。非推奨エンドポイントを使用している古いコードは、非推奨エンドポイントの使用を中止するように更新する必要があります。Looker の今後のリリースで、そのエンドポイントのサポートが終了すると、そのエンドポイントを使用しているコードは機能しなくなります。非推奨エンドポイントは、ほとんどの場合、改善された機能で置き換えられます。非推奨の関数やプロパティをアプリケーションが使用していることに気付いた場合は、コードをリファクタリングして、非推奨の要素をできるだけ早く置き換えることをおすすめします。
ベータ版エンドポイントと非推奨エンドポイントは、API Explorer と 4.0 API リファレンスのように示されています。マークされていないエンドポイントは安定しているとみなされます。
新しい API バージョンへの移行
クライアント SDK または API の URL を新しい API バージョンにアップグレードした場合は、アプリケーション コードを調べて、新しい API バージョンによって変更されたものに依存しているかどうかを確認する必要があります。次のことを行ってください。
- 更新された関数、値、プロパティ名について、アプリケーション コードを検索します。
- アプリケーション コードで型の変更（整数から文字列など）がサポートされていることを確認します。
- コードを監査します（コードの監査をご覧ください）。
コードの監査
一部の言語では、API の互換性を損なう変更をビルド時にコンパイル エラーとして検出できます。
- コンパイル済みの厳密に型指定された言語でアプリケーションが作成されている場合、既存のコードとは異なる新しい API バージョンでのパラメータ型やレスポンス型の構造変更は、コンパイル型チェックとコンパイラのエラー メッセージによりすぐにわかります。
- アプリケーションが大まかに型指定された動的言語（JavaScript、Ruby、Python など）で作成されている場合、新しい API バージョンへの互換性を損なう変更によって影響を受けるアプリケーションの部分を特定するのが難しくなることがあります。これらのタイプの言語では、型の変更に関連する問題を見つけるためにランタイム単体テストが必要になる場合があります。
いずれの場合でも、Looker API の呼び出し（モック呼び出しではない）など、アプリケーション コードを実行する単体テストを用意することをおすすめします。