Menangani pembuatan versi API

Halaman ini menjelaskan cara melakukan pembuatan versi untuk API Anda dan cara men-deploy ke beberapa versi.

Rekomendasi untuk mengelola versi API

Dalam mengelola versi API, pertimbangkan rekomendasi berikut:

  • Jika Anda ingin memperkenalkan perubahan inkremental, tetapi tidak merusak, pertahankan versi API tetap dan deploy melalui API yang ada.
  • Saat Anda memperkenalkan perubahan yang dapat menyebabkan gangguan pada API, tingkatkan versi API.
  • Untuk perlindungan tambahan, tingkatkan juga versi aplikasi App Engine, lalu deploy versi API baru ke versi aplikasi App Engine baru tersebut. Hal ini memungkinkan Anda menggunakan fleksibilitas bawaan App Engine untuk beralih dengan cepat di antara versi App Engine dan menayangkan dari versi lama yang berfungsi jika Anda mengalami masalah yang tidak terduga.

Tabel berikut adalah ilustrasi versi API backend cascading ke versi aplikasi App Engine yang berbeda.

Versi aplikasi Versi Backend API
1
  • v1 --> v1 (2) --> v1 (n)
2
  • v1 (n)
  • v2 --> v2 (2) --> v2 (n)
3
  • v1 (n)
  • v2 (n)
  • v3 --> v3 (2) --> v3 (n)

Seperti yang ditunjukkan dalam tabel, update inkremental yang tidak mengganggu pada API v1 diluncurkan, dan setiap update akan menimpa versi sebelumnya. Saat perubahan yang dapat menyebabkan gangguan diperkenalkan, versi API akan bertambah menjadi v2 dan di-deploy ke versi aplikasi App Engine yang baru. Hal ini memungkinkan Anda beralih kembali ke versi aplikasi sebelumnya jika diperlukan.

Dalam tabel, perhatikan bahwa versi aplikasi 2 mendukung versi v1 terbaru dan versi v2 baru API Anda. Jika Anda tidak menghapus kode v1 yang ada dari project, saat men-deploy project, v2 dan vl (n) API akan di-deploy ke aplikasi versi 2.

Men-deploy ke beberapa versi aplikasi

Saat men-deploy API backend, Anda men-deploynya ke project ID project Google Cloud yang Anda buat untuk API, dan Anda juga harus menentukan versi App Engine tempat Anda men-deploy. Anda menentukan versi aplikasi App Engine di elemen <version> pada file /WEB-INF/appengine-web.xml. Versi aplikasi App Engine tidak sama dengan nomor versi API backend, yang Anda tentukan dalam atribut version dari anotasi @Api.

apiversions

Seperti yang ditunjukkan pada gambar sebelumnya, Anda dapat men-deploy beberapa versi API ke versi App Engine yang sama. Selain itu, Anda dapat memiliki banyak versi App Engine untuk satu aplikasi.

Mengakses versi API yang di-deploy ke versi penayangan

Versi App Engine pertama yang Anda gunakan untuk men-deploy API adalah versi penayangan. Versi ini berjalan di URL http://YOUR_PROJECT_ID.appspot.com dengan YOUR_PROJECT_ID mewakili project ID Google Cloud Anda. Anda dapat mengakses semua versi API yang di-deploy ke versi aplikasi App Engine tersebut menggunakan URL tersebut.

Versi penayangan tetap sama hingga Anda mengubahnya secara eksplisit, di konsol Google Cloud.

Mengakses versi API yang di-deploy ke versi aplikasi yang tidak ditayangkan

Jika perlu mengakses versi API yang tidak di-deploy ke versi App Engine yang saat ini menayangkan, Anda menggunakan URL khusus versi, mirip dengan berikut:

https://VERSION-dot-YOUR_PROJECT_ID.appspot.com

Ganti VERSION dengan versi App Engine Anda, dan YOUR_PROJECT_ID dengan ID project Google Cloud Anda. Misalnya, versi penayangan App Engine Anda adalah 1, tetapi Anda ingin mengakses versi API yang di-deploy ke versi 2. Anda akan menggunakan URL ini: https://2-dot-YOUR_PROJECT_ID.appspot.com.

Untuk mengetahui detail selengkapnya, lihat dokumentasi App Engine.

Mengakses versi API yang di-deploy ke layanan non-penayangan (sebelumnya modul)

Jika perlu mengakses versi API yang tidak di-deploy ke layanan App Engine default, Anda dapat menggunakan URL khusus layanan menggunakan sintaksis titik sebagai berikut:

https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...

Untuk mengetahui detail selengkapnya, lihat dokumentasi App Engine.