Sebagian besar aplikasi ditulis menggunakan beberapa bentuk SDK klien, atau mungkin URL API. URL API dan SDK klien terikat dengan versi Looker API tertentu. Aplikasi Anda akan terus berfungsi meskipun Looker membuat perubahan pada versi API baru. Aplikasi Anda tidak akan terpengaruh oleh perubahan pada versi API lainnya hingga Anda memilih untuk mengupgrade SDK klien (atau mengubah URL API) untuk menggunakan versi Looker API yang baru.
Cara Looker membuat perubahan pada API
Looker API dirancang untuk memberikan stabilitas endpoint Looker API, sehingga meningkatkan stabilitas aplikasi Anda.
Seiring bertambahnya fitur dan kemampuan Looker, kami juga memperbarui Looker REST API untuk mengakses atau mengelola fitur baru tersebut. Untuk setiap rilis Looker, kami menambahkan fungsi API, parameter, dan properti jenis respons baru ke Looker API versi saat ini. Umumnya, penambahan pada API bukan perubahan yang dapat menyebabkan gangguan, sehingga kita dapat mempertahankan versi API yang ada tanpa memengaruhi kode aplikasi yang sudah ada dan yang dibuat menggunakan API tersebut. Kode aplikasi yang ada mungkin tidak mengetahui fungsi, parameter, atau fitur baru yang muncul dalam rilis Looker berikutnya.
Untuk perubahan pada API yang dapat merusak kode aplikasi yang ada, kami memaketkan perubahan yang dapat menyebabkan gangguan tersebut ke dalam versi API baru. Ini berarti bahwa versi API lama akan terus berfungsi seperti sebelumnya, sementara versi API baru akan berjalan bersamaan dengan perubahan dan update. Beberapa versi API dapat muncul berdampingan dalam satu instance Looker, sehingga Anda dapat memilih kapan akan mengupgrade ke versi API baru. Kode yang ada yang dibuat untuk memanggil endpoint lama akan terus memanggil endpoint lama. Kode baru harus memanggil versi baru endpoint di level versi API terbaru.
Satu pengecualian untuk hal ini adalah untuk masalah keamanan kritis. Jika kami menemukan masalah keamanan kritis yang terkait dengan bagian tertentu dari API, kami akan melakukan tindakan apa pun yang diperlukan untuk memitigasi masalah keamanan tersebut sesegera mungkin, yang mungkin termasuk menonaktifkan fungsi yang rentan hingga solusi yang tepat tersedia).
Jika kita perlu menghentikan fitur, fungsi, atau properti untuk memberi cara bagi implementasi atau solusi yang lebih baik, kita biasanya membiarkan API saat ini sebagaimana adanya, tetapi menandai endpoint API yang terkait sebagai "tidak digunakan lagi" untuk menunjukkan bahwa Anda harus beralih dari endpoint dalam kode aplikasi.
Perubahan yang dapat menyebabkan gangguan dan aditif pada API
Perubahan yang dapat menyebabkan gangguan adalah sesuatu yang menghapus atau mengganti nama artefak endpoint API yang sudah ada. Ini mungkin termasuk:
- Mengubah atau menghapus nama atau jenis parameter
- Menambahkan parameter baru yang diperlukan
- Mengubah URL dasar
- Mengubah atau menghapus properti yang ada dalam respons
Di sisi lain, perubahan aditif dapat dilakukan ke endpoint stabil. Mungkin termasuk:
- Parameter opsional baru
- Properti baru dalam respons (kami tidak menganggap hal ini dapat menyebabkan gangguan karena kami menganggap kode Anda akan mengabaikan properti yang tidak diketahui dalam respons, yang merupakan praktik umum dalam komunitas REST API)
Jika endpoint Looker API stabil memerlukan perubahan signifikan agar dapat beralih dengan arsitektur atau fungsi baru, perubahan tersebut biasanya ditambahkan ke endpoint baru dan dipaketkan ke dalam versi API baru sehingga endpoint API yang ada tetap tidak berubah.
Tanda untuk endpoint API
Sebagian besar endpoint API dianggap stabil, artinya tidak akan berubah. Looker tidak akan merilis perubahan yang dapat menyebabkan gangguan ke 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 pada masa mendatang. Mereka tidak terlindungi dari perubahan yang dapat menyebabkan gangguan. Saat menggunakan endpoint beta, pertimbangkan apakah perubahan pada Looker API akan sangat mengganggu siklus pengembangan atau aplikasi Anda. Baca catatan rilis Looker jika Anda berencana menggunakan endpoint beta agar Anda dapat mengetahui setiap perubahan.
- Endpoint yang tidak digunakan lagi adalah endpoint yang masih didukung dan masih dapat digunakan saat ini, tetapi akan dihapus pada rilis mendatang. Kode lama yang menggunakan endpoint yang tidak digunakan lagi harus diperbarui agar berhenti menggunakan endpoint yang tidak digunakan lagi. Saat rilis Looker mendatang menghapus dukungan untuk endpoint tersebut, kode apa pun yang masih menggunakannya akan rusak. Pada umumnya, endpoint yang sudah tidak digunakan lagi akan diganti dengan fungsi yang lebih baik. Jika Anda mendapati bahwa aplikasi Anda menggunakan fungsi atau properti yang tidak digunakan lagi, ada baiknya Anda memfaktorkan ulang kode untuk mengganti elemen yang tidak digunakan lagi sesegera mungkin.
Endpoint beta dan yang tidak digunakan lagi ditandai sedemikian rupa di API Explorer dan di Referensi API 4.0. Endpoint yang tidak ditandai dianggap stabil.
Bermigrasi ke versi API baru
Jika 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 menemukan fungsi, nilai, dan nama properti yang diperbarui.
- Pastikan kode aplikasi Anda mendukung setiap perubahan jenis (seperti bilangan bulat ke string).
- Audit kode Anda (lihat bagian di bawah).
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, berjenis kuat, perubahan struktural pada parameter atau jenis respons dalam versi API baru yang bertentangan dengan kode yang ada harus terlihat jelas berkat pemeriksaan jenis kompilasi dan pesan error compiler.
- Jika aplikasi Anda ditulis dalam bahasa dinamis yang diketik secara longgar (seperti JavaScript, Ruby, dan Python), mungkin akan lebih sulit untuk 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 yang terkait dengan perubahan jenis.
Dalam semua kasus, praktik terbaiknya adalah memiliki pengujian unit yang menjalankan kode aplikasi Anda, termasuk panggilan ke Looker API (bukan panggilan tiruan).