Sebagian besar aplikasi ditulis menggunakan beberapa bentuk SDK klien, atau mungkin URL API. URL API dan SDK klien 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 di 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 pada endpoint Looker API, dan oleh karena itu, stabilitas pada 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 pada API bukanlah perubahan yang menyebabkan gangguan, sehingga kita dapat mempertahankan versi API yang ada tanpa memengaruhi kode aplikasi yang ada yang dibangun di atas API. Kode aplikasi 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 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 waktu untuk 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-satunya pengecualian untuk hal ini adalah masalah keamanan kritis. Jika kami menemukan masalah keamanan kritis yang terkait dengan bagian tertentu dari API, kami akan melakukan apa pun yang diperlukan untuk mengurangi masalah keamanan tersebut sesegera mungkin, yang dapat mencakup menonaktifkan fungsi yang rentan hingga solusi yang tepat tersedia).
Jika kami perlu menghentikan penggunaan fitur, fungsi, atau properti untuk memberikan 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 tersebut dalam kode aplikasi Anda.
Perubahan yang dapat menyebabkan gangguan dan perubahan tambahan pada API
Perubahan yang dapat menyebabkan gangguan adalah perubahan yang menghapus atau mengganti nama artefak endpoint API yang ada. Hal ini dapat mencakup:
- Mengubah atau menghapus nama atau jenis parameter
- Menambahkan parameter wajib baru
- Mengubah URL dasar
- Mengubah atau menghapus properti yang ada dalam respons
Di sisi lain, perubahan aditif dapat dilakukan pada endpoint stabil. Hal ini dapat mencakup:
- Parameter opsional baru
- Properti baru dalam respons (kami tidak menganggap ini sebagai perubahan yang merusak 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 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 akan berubah. Looker tidak akan merilis perubahan yang merusak 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. API tersebut tidak dilindungi dari perubahan yang merusak. 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 dapat digunakan saat ini, tetapi akan dihapus dalam rilis mendatang. Kode lama yang menggunakan endpoint yang tidak digunakan lagi harus diupdate agar tidak 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 digantikan oleh fungsi yang lebih baik. Jika Anda mendapati bahwa aplikasi Anda menggunakan fungsi atau properti yang tidak digunakan lagi, sebaiknya refaktorkan kode Anda untuk mengganti elemen yang tidak digunakan lagi sesegera mungkin.
Endpoint beta dan yang tidak digunakan lagi ditandai demikian di API Explorer dan di 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 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 menemukan nama fungsi, nilai, dan properti yang telah diupdate.
- Pastikan kode aplikasi Anda mendukung perubahan jenis apa pun (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 memiliki pengetikan yang kuat, perubahan struktural pada jenis parameter atau respons dalam versi API baru yang tidak sesuai dengan kode yang ada akan terlihat jelas berkat pemeriksaan jenis kompilasi dan pesan error compiler.
- Jika aplikasi Anda ditulis dalam bahasa dinamis yang tidak memiliki pengetikan yang ketat (seperti JavaScript, Ruby, dan Python), mungkin akan lebih sulit untuk menemukan bagian aplikasi yang akan terpengaruh oleh perubahan yang menyebabkan gangguan pada 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 yang di-mock).