Pembuatan Versi

Topik ini menjelaskan strategi pembuatan versi yang digunakan oleh Google API. Secara umum, strategi ini berlaku untuk semua layanan yang dikelola Google.

Terkadang, Anda perlu membuat perubahan yang tidak kompatibel dengan versi sebelumnya (atau yang "bermasalah") pada API. Perubahan semacam ini dapat menyebabkan masalah atau kerusakan untuk kode yang memiliki dependensi pada fungsi aslinya.

Google API menggunakan skema pembuatan versi untuk mencegah perubahan yang dapat menyebabkan gangguan. Selain itu, beberapa fungsi Google API hanya tersedia pada tingkat stabilitas tertentu, seperti komponen alfa dan beta.

Panduan

Semua antarmuka Google API harus menyediakan nomor versi utama, yang dienkode di akhir paket protobuf, dan disertakan sebagai bagian pertama dari jalur URI untuk REST API. Jika API memperkenalkan perubahan yang dapat menyebabkan gangguan, seperti menghapus atau mengganti nama kolom, API harus menambah nomor versi API-nya untuk memastikan kode pengguna yang ada tidak tiba-tiba rusak.

Catatan: Penggunaan istilah "nomor versi utama" di atas diambil dari pembuatan versi semantik. Namun, berbeda dengan pembuatan versi semantik tradisional, Google API tidak boleh mengekspos nomor versi minor atau patch. Misalnya, Google API menggunakan v1, bukan v1.0, v1.1, atau v1.4.2. Dari perspektif pengguna, versi utama akan diupdate, dan pengguna menerima fungsi baru tanpa migrasi.

Versi utama baru dari API tidak boleh bergantung pada versi utama sebelumnya dari API yang sama. API mungkin bergantung pada API lain, dengan ekspektasi bahwa pemanggil memahami risiko dependensi dan stabilitas yang terkait dengan API tersebut. Dalam skenario ini, versi API stabil harus hanya bergantung pada versi stabil API lainnya.

Berbagai versi API yang sama harus dapat berfungsi secara bersamaan dalam satu aplikasi klien selama periode transisi yang wajar. Periode waktu ini memungkinkan klien untuk melakukan transisi dengan lancar ke versi yang lebih baru. Versi yang lebih lama harus melalui periode penghentian penggunaan yang wajar dan dikomunikasikan dengan baik sebelum dinonaktifkan.

Untuk rilis yang memiliki stabilitas alfa atau beta, API harus menambahkan tingkat stabilitas setelah nomor versi utama dalam paket protobuf dan jalur URI menggunakan salah satu strategi berikut:

• Pembuatan versi berbasis channel (direkomendasikan)
• Pembuatan versi berbasis rilis
• Pembuatan versi berbasis visibilitas

Pembuatan versi berbasis saluran

Saluran stabilitas adalah rilis yang berdurasi panjang pada tingkat stabilitas tertentu yang menerima update bawaan. Tidak ada lebih dari satu saluran per level stabilitas untuk versi utama. Dalam strategi ini, tersedia hingga tiga saluran: alfa, beta, dan stabil.

Saluran alfa dan beta harus ditambahkan tingkat stabilitasnya ke versi, tetapi tingkat stabilitas tidak boleh ditambahkan ke saluran stabil. Misalnya, v1 adalah versi yang dapat diterima untuk saluran stabil, tetapi v1beta atau v1alpha tidak. Demikian pula, v1beta atau v1alpha adalah versi yang dapat diterima untuk masing-masing saluran beta dan alfa, tetapi v1 tidak dapat diterima untuk keduanya. Setiap saluran ini menerima pembaruan dan fitur baru "di tempat".

Fungsi saluran beta harus menjadi superset dari fungsi saluran stabil, dan fungsi saluran alfa harus menjadi superset dari fungsi saluran beta.

Penghentian fungsi API

Elemen API (kolom, pesan, RPC) dapat ditandai sebagai tidak digunakan lagi di saluran mana pun untuk menunjukkan bahwa elemen tersebut tidak boleh digunakan lagi:

// Represents a scroll. Books are preferred over scrolls.
message Scroll {
  option deprecated = true;

  // ...
}

Fungsi API yang tidak digunakan lagi tidak boleh beralih dari alfa ke beta, atau beta ke stabil. Dengan kata lain, fungsi tidak boleh berstatus "tidak digunakan lagi" di saluran mana pun.

Fungsi saluran beta dapat dihapus setelah tidak digunakan lagi selama jangka waktu yang cukup; sebaiknya selama 180 hari. Untuk fungsi yang hanya ada di saluran alfa, penghentian penggunaan bersifat opsional, dan fungsi dapat dihapus tanpa pemberitahuan. Jika fungsi tidak digunakan lagi di saluran alfa API sebelum dihapus, API harus menerapkan anotasi yang sama, dan dapat menggunakan jangka waktu apa pun yang diinginkan.

Pembuatan versi berbasis rilis

Rilis individual adalah rilis alfa atau beta yang diharapkan akan tersedia untuk jangka waktu terbatas sebelum fungsinya digabungkan ke saluran stabil, setelah itu rilis individual akan dihentikan. Saat menggunakan strategi pembuatan versi berbasis rilis, API dapat memiliki berapa pun rilis pada setiap tingkat stabilitas.

Catatan: Strategi berbasis saluran dan berbasis rilis akan memperbarui versi stabil. Ada satu saluran stabil, bukan rilis stabil masing-masing, bahkan saat menggunakan strategi berbasis rilis.

Rilis alfa dan beta harus memiliki level stabilitas yang ditambahkan ke versi, diikuti dengan nomor rilis yang bertambah. Misalnya, v1beta1 atau v1alpha5. API harus mendokumentasikan urutan kronologis versi ini dalam dokumentasinya (seperti komentar).

Setiap rilis alfa atau beta dapat diupdate dengan perubahan yang kompatibel dengan versi lama. Untuk rilis beta, update inkompatibilitas mundur harus dibuat dengan menambah angka rilis dan memublikasikan rilis baru bersama perubahan tersebut. Misalnya, jika versi saat ini adalah v1beta1, maka v1beta2 akan dirilis berikutnya.

Rilis alfa dan beta harus dinonaktifkan setelah fungsinya mencapai saluran stabil. Rilis alfa dapat dihentikan kapan saja, sedangkan rilis beta harus memberikan periode transisi yang wajar bagi pengguna; sebaiknya 180 hari.

Pembuatan versi berbasis visibilitas

Visibilitas API adalah fitur lanjutan yang disediakan oleh infrastruktur Google API. Hal ini memungkinkan produsen API mengekspos beberapa tampilan API eksternal dari satu platform API internal, dan setiap tampilan dikaitkan dengan label visibilitas API, seperti:

import "google/api/visibility.proto";

message Resource {
  string name = 1;

  // Preview. Do not use this feature for production.
  string display_name = 2
    [(google.api.field_visibility).restriction = "PREVIEW"];
}

Label visibilitas adalah string peka huruf besar/kecil yang dapat digunakan untuk memberi tag pada elemen API. Berdasarkan konvensi, label visibilitas harus selalu menggunakan HURUF BESAR. Label PUBLIC implisit diterapkan ke semua elemen API, kecuali jika label visibilitas eksplisit diterapkan seperti dalam contoh di atas.

Setiap label visibilitas merupakan daftar yang diizinkan. Produsen API perlu memberikan label visibilitas kepada konsumen API agar mereka dapat menggunakan fitur API yang terkait dengan label. Dengan kata lain, label visibilitas API seperti versi API ACL.

Beberapa label visibilitas dapat diterapkan pada elemen dengan menggunakan string yang dipisahkan koma (misalnya, "PREVIEW,TRUSTED_TESTER"). Saat beberapa label visibilitas digunakan, klien hanya memerlukan salah satu label visibilitas (OR logis).

Satu permintaan API hanya dapat menggunakan satu label visibilitas. Secara default, label visibilitas yang diberikan kepada konsumen API akan digunakan. Klien dapat mengirim permintaan dengan label visibilitas eksplisit sebagai berikut:

GET /v1/projects/my-project/topics HTTP/1.1
Host: pubsub.googleapis.com
Authorization: Bearer y29....
X-Goog-Visibilities: PREVIEW

Produsen API dapat menggunakan visibilitas API untuk pembuatan versi API, seperti INTERNAL dan PREVIEW. Fitur API baru dimulai dengan label INTERNAL, lalu dipindahkan ke label PREVIEW. Setelah fitur stabil dan tersedia secara umum, semua label visibilitas API akan dihapus dari definisi API.

Secara umum, visibilitas API lebih mudah diimplementasikan daripada pembuatan versi API untuk perubahan inkremental, tetapi bergantung pada dukungan infrastruktur API yang canggih. Google Cloud API sering menggunakan visibilitas API untuk fitur Pratinjau.