Pembuatan versi Looker API

Sebagian besar aplikasi ditulis menggunakan beberapa bentuk SDK klien, atau mungkin URL API. SDK klien dan URL API terikat dengan 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 yang baru.

Cara Looker membuat perubahan pada API

Looker API dirancang untuk memberikan stabilitas bagi endpoint Looker API, sehingga memberikan stabilitas bagi aplikasi Anda.

Seiring penambahan 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 Looker API versi saat ini. Dalam sebagian besar kasus, penambahan ke API bukanlah perubahan yang menyebabkan gangguan, sehingga kita dapat mempertahankan versi API yang ada tanpa memengaruhi kode aplikasi yang ada yang dibuat di 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 memaketkan 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 bersamanya dengan perubahan dan update. Beberapa versi API dapat digunakan secara 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 level versi API terbaru.

Satu pengecualian untuk hal ini adalah masalah keamanan penting. Jika kami menemukan masalah keamanan kritis yang terkait dengan bagian API tertentu, kami akan melakukan apa pun yang diperlukan untuk memitigasi masalah keamanan tersebut sesegera mungkin, yang dapat mencakup menonaktifkan fungsi yang rentan hingga solusi yang tepat tersedia).

Jika kami perlu menghentikan fitur, fungsi, atau properti untuk membuka jalan bagi implementasi atau solusi yang lebih baik, kami biasanya membiarkan API saat ini 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 perubahan tambahan pada API

Perubahan yang dapat menyebabkan gangguan adalah sesuatu yang menghapus atau mengganti nama artefak endpoint API yang ada. Hal ini dapat mencakup:

  • 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 pada endpoint stabil. Hal ini dapat mencakup:

  • Parameter baru yang opsional
  • Properti baru dalam respons (kami tidak menganggap hal ini sebagai gangguan karena kami mengasumsikan bahwa kode Anda akan mengabaikan properti yang tidak diketahui dalam respons, yang merupakan praktik umum di komunitas REST API)

Jika endpoint Looker API yang stabil memerlukan perubahan signifikan untuk melanjutkan 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.

Flag untuk endpoint API

Sebagian besar endpoint API dianggap stabil, yang berarti endpoint tersebut tidak akan berubah. Looker tidak akan merilis perubahan yang menyebabkan gangguan ke endpoint stabil kecuali dalam kasus ekstrem, seperti untuk memperbaiki masalah keamanan.

Endpoint API lainnya mungkin ditandai sebagai beta atau tidak digunakan lagi:

  • Endpoint beta sedang dalam pengembangan aktif dan dapat berubah di masa mendatang. Perubahan 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 masih dapat digunakan saat ini, tetapi akan dihapus dalam rilis mendatang. Kode lama yang menggunakan endpoint yang tidak digunakan lagi harus diperbarui agar tidak lagi 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 lebih baik. Jika Anda mendapati bahwa aplikasi Anda menggunakan fungsi atau properti yang tidak digunakan lagi, sebaiknya faktorkan ulang 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.

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:

  1. Telusuri kode aplikasi Anda untuk menemukan nama fungsi, nilai, dan properti yang diperbarui.
  2. Pastikan kode aplikasi Anda mendukung perubahan jenis apa pun (seperti bilangan bulat ke string).
  3. Audit kode Anda (lihat bagian Audit kode Anda).

Mengaudit kode Anda

Untuk beberapa bahasa, perubahan yang menyebabkan error di API dapat ditemukan pada waktu build sebagai error kompilasi:

  • Jika aplikasi Anda ditulis dalam bahasa yang dikompilasi dan memiliki jenis yang kuat, perubahan struktural pada parameter atau jenis respons dalam versi API baru yang bertentangan dengan kode yang ada akan segera terlihat berkat pemeriksaan jenis kompilasi dan pesan error compiler.
  • Jika aplikasi Anda ditulis dalam bahasa dinamis dengan jenis longgar (seperti JavaScript, Ruby, dan Python), mungkin akan lebih sulit untuk menemukan bagian aplikasi yang akan terpengaruh oleh perubahan yang menyebabkan error 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).