Sebagian besar aplikasi ditulis menggunakan beberapa bentuk SDK klien, atau mungkin URL API. SDK klien dan URL API terikat ke versi Looker API tertentu. Aplikasi Anda akan terus berfungsi meskipun Looker melakukan perubahan pada versi API baru. Aplikasi Anda tidak akan terpengaruh oleh perubahan pada versi API lain hingga Anda memilih untuk mengupgrade SDK klien (atau mengubah URL API) untuk menggunakan versi Looker API baru.
Cara Looker melakukan perubahan pada API
Looker API dirancang untuk memberikan stabilitas bagi endpoint Looker API, dan oleh karena itu, stabilitas bagi aplikasi Anda.
Saat kami menambahkan lebih banyak fitur dan kemampuan ke Looker, kami juga memperbarui Looker REST API untuk mengakses atau mengelola fitur baru tersebut. Untuk setiap rilis Looker, kami menambahkan fungsi, parameter, dan properti jenis respons API baru ke versi Looker API saat ini. Dalam sebagian besar kasus, penambahan ke API tidak menyebabkan perubahan yang dapat menyebabkan gangguan, sehingga kami dapat mempertahankan versi API yang ada tanpa memengaruhi kode aplikasi yang ada yang dibuat di API. Kode aplikasi Anda yang ada mungkin tidak mengetahui fungsi, parameter, atau fitur baru yang muncul dalam rilis Looker berikutnya.
Untuk perubahan pada API yang akan merusak kode aplikasi yang ada, kami menggabungkan perubahan yang dapat menyebabkan gangguan tersebut ke dalam versi API baru. Artinya, versi API lama akan terus berfungsi seperti sebelumnya, sementara versi API baru berjalan bersamaan dengan perubahan dan update. Beberapa versi API dapat berdampingan dalam satu instance Looker sehingga Anda dapat memilih kapan harus mengupgrade ke versi API baru. Kode yang ada yang dibuat untuk memanggil endpoint lama akan terus memanggil endpoint lama. Kode baru harus memanggil endpoint versi baru di tingkat versi API terbaru.
Satu pengecualian untuk hal ini adalah untuk masalah keamanan penting. Jika kami menemukan masalah keamanan penting yang terkait dengan bagian tertentu dari API, kami akan melakukan apa pun yang diperlukan untuk mengurangi masalah keamanan tersebut sesegera mungkin, yang mungkin mencakup menonaktifkan fungsi yang rentan hingga solusi yang tepat tersedia).
Jika kami perlu menghentikan fitur, fungsi, atau properti untuk memberi ruang bagi penerapan atau solusi yang lebih baik, kami biasanya membiarkan API saat ini seperti apa adanya, tetapi menandai endpoint API terkait sebagai "tidak digunakan lagi" untuk menunjukkan bahwa Anda harus beralih dari endpoint dalam kode aplikasi Anda.
Perubahan yang dapat menyebabkan gangguan dan penambahan pada API
Perubahan yang dapat menyebabkan gangguan adalah sesuatu yang menghapus atau mengganti nama artefak endpoint API yang ada. Perubahan ini mungkin mencakup:
- Mengubah atau menghapus nama atau jenis parameter
- Menambahkan parameter wajib baru
- Mengubah URL dasar
- Mengubah atau menghapus properti yang ada dalam respons
Sebaliknya, perubahan penambahan dapat dilakukan pada endpoint stabil. Perubahan ini mungkin mencakup:
- Parameter opsional baru
- Properti baru dalam respons (kami tidak menganggap ini sebagai perubahan yang dapat menyebabkan gangguan karena kami mengasumsikan bahwa kode Anda akan mengabaikan properti yang tidak diketahui dalam respons, yang merupakan praktik umum dalam komunitas REST API)
Jika endpoint Looker API yang stabil memerlukan perubahan signifikan untuk melanjutkan arsitektur atau fungsi baru, perubahan tersebut biasanya ditambahkan ke endpoint baru dan digabungkan ke dalam versi API baru sehingga endpoint API yang ada tetap tidak berubah.
Flag untuk endpoint API
Sebagian besar endpoint API dianggap stabil, yang berarti endpoint tersebut tidak diharapkan berubah. Looker tidak akan merilis perubahan yang dapat menyebabkan gangguan pada endpoint stabil kecuali dalam kasus ekstrem, seperti untuk memperbaiki masalah keamanan.
Endpoint API lainnya dapat ditandai sebagai beta atau tidak digunakan lagi:
- Endpoint beta sedang dalam pengembangan aktif dan dapat berubah di masa mendatang. Endpoint ini tidak dilindungi dari perubahan yang dapat menyebabkan gangguan. Saat menggunakan endpoint beta, pertimbangkan apakah perubahan pada Looker API akan sangat mengganggu aplikasi atau siklus pengembangan Anda. Baca catatan rilis Looker jika Anda berencana menggunakan endpoint beta agar Anda mengetahui perubahan apa pun.
- Endpoint yang tidak digunakan lagi adalah endpoint yang masih didukung dan masih dapat digunakan saat ini, tetapi akan dihapus dalam rilis mendatang. Kode lama yang menggunakan endpoint yang tidak digunakan lagi harus diupdate agar berhenti menggunakan endpoint yang tidak digunakan lagi. Jika rilis Looker mendatang menghapus dukungan untuk endpoint tersebut, kode apa pun yang masih menggunakannya akan rusak. Dalam sebagian besar kasus, endpoint yang tidak digunakan lagi akan diganti dengan fungsi yang ditingkatkan. Jika Anda menemukan bahwa aplikasi Anda menggunakan fungsi atau properti yang tidak digunakan lagi, sebaiknya perbaiki kode Anda untuk mengganti elemen yang tidak digunakan lagi sesegera mungkin.
Endpoint beta dan yang tidak digunakan lagi ditandai sebagai endpoint tersebut di API Explorer dan dalam Referensi API 4.0. Endpoint yang tidak ditandai dianggap stabil.
Jenis panggilan API
Jenis panggilan API yang ditentukan sebagai panggilan API kueri adalah sebagai berikut:
- Panggilan yang diperlukan untuk pipeline kueri otomatis
- Panggilan yang mendapatkan data dari database klien
- Panggilan yang menjalankan kueri SQL atau mengambil hasil untuk konten
Contohnya mencakup:
Jenis panggilan API yang ditentukan sebagai panggilan API admin adalah sebagai berikut:
- Panggilan yang diperlukan untuk membuat aplikasi, mengontrol konten di seluruh instance, dan melakukan tugas administratif
- Panggilan yang mengontrol instance Looker (Google Cloud core)
- Panggilan yang melakukan pengelolaan konten, pengelolaan izin dan pengguna, administrasi instance, atau menarik konten di seluruh folder
Contohnya mencakup:
Bermigrasi ke versi API baru
Saat Anda memilih untuk mengupgrade SDK klien atau URL API ke versi API baru, Anda harus meninjau kode aplikasi untuk melihat apakah Anda mengandalkan sesuatu yang telah berubah dengan versi API baru. Pastikan untuk melakukan hal berikut:
- Telusuri kode aplikasi Anda untuk nama fungsi, nilai, dan properti yang diperbarui.
- Pastikan kode aplikasi Anda mendukung perubahan jenis (seperti bilangan bulat ke string).
- Audit kode Anda (lihat bagian Mengaudit kode Anda).
Mengaudit kode Anda
Untuk beberapa bahasa, perubahan yang dapat menyebabkan gangguan pada API dapat ditemukan pada waktu build sebagai error kompilasi:
- Jika aplikasi Anda ditulis dalam bahasa yang dikompilasi dan berjenis kuat, perubahan struktural pada jenis parameter atau respons dalam versi API baru yang bertentangan dengan kode yang ada akan terlihat jelas berkat pemeriksaan jenis kompilasi dan pesan error kompilator.
- Jika aplikasi Anda ditulis dalam bahasa dinamis yang berjenis lemah (seperti JavaScript, Ruby, dan Python), mungkin akan lebih sulit menemukan bagian aplikasi yang akan terpengaruh oleh perubahan yang dapat menyebabkan gangguan dalam versi API baru. Jenis bahasa ini mungkin memerlukan pengujian unit runtime untuk menemukan masalah terkait perubahan jenis.
Dalam semua kasus, praktik terbaiknya adalah memiliki pengujian unit yang menjalankan kode aplikasi Anda, termasuk panggilan ke Looker API (bukan panggilan tiruan).