Bagikan melalui

Versi di Azure API Management

  • Artikel

BERLAKU UNTUK: Semua tingkatAN API Management

Versi memungkinkan Anda menyajikan grup API terkait ke pengembang Anda. Anda dapat menggunakan versi untuk menangani perubahan yang merusak (breaking change) di API dengan aman. Klien dapat memilih untuk menggunakan versi API baru Anda saat mereka siap, sementara klien yang ada terus menggunakan versi yang lebih lama. Versi dibedakan melalui pengidentifikasi versi (yang merupakan nilai string apa pun yang Anda pilih), dan skema penerapan versi memungkinkan klien untuk mengidentifikasi versi API mana yang ingin mereka gunakan.

Untuk sebagian besar tujuan, setiap versi API dapat dianggap sebagai API independennya sendiri. Dua versi API yang berbeda mungkin memiliki rangkaian operasi yang berbeda dan kebijakan yang berbeda.

Dengan versi, Anda dapat:

  • Menerbitkan beberapa versi API Anda secara bersamaan.
  • Menggunakan jalur, string kueri, atau header untuk membedakan antara versi.
  • Menggunakan nilai string apa pun yang inginkan untuk mengidentifikasi versi Anda, bisa berupa angka, tanggal, atau nama.
  • Menampilkan versi API Anda yang dikelompokkan bersama di portal pengembang.
  • Mengambil API yang sudah ada (non-versi), dan membuat versi barunya tanpa merusak klien yang sudah ada.

Mulai menggunakan versi dengan mengikuti panduan kami.

Skema penerapan versi

Pengembang API yang berbeda memiliki berbagai persyaratan untuk penerapan versi. Azure API Management tidak menentukan satu pendekatan untuk penerapan versi, tetapi menyediakan beberapa opsi.

Penerapan versi berbasis jalur

Ketika skema pembuatan versi jalur digunakan, pengidentifikasi versi harus disertakan dalam jalur URL untuk setiap permintaan API.

Misalnya, https://apis.contoso.com/products/v1 dan https://apis.contoso.com/products/v2 dapat merujuk ke API products yang sama tetapi ke versi v1 dan v2 masing-masing.

Format URL permintaan API saat menggunakan penerapan versi berbasis jalur adalah: https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Penerapan versi berbasis header

Ketika skema penerapan versi header digunakan, pengidentifikasi versi perlu disertakan dalam header permintaan HTTP untuk permintaan API apa pun. Anda dapat menentukan nama header permintaan HTTP.

Misalnya, Anda dapat membuat header kustom bernama Api-Version, dan klien dapat menentukan v1 atau v2 dalam nilai header ini.

Pembuatan versi berbasis string kueri

Saat skema penerapan versi string kueri digunakan, pengidentifikasi versi harus disertakan dalam parameter string kueri untuk setiap permintaan API. Anda bisa menentukan nama parameter string kueri.

Format URL permintaan API saat menggunakan penerapan versi berbasis string kueri adalah: https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

Misalnya, https://apis.contoso.com/products?api-version=v1 dan https://apis.contoso.com/products?api-version=v2 dapat merujuk ke API products yang sama tetapi ke versi v1 dan v2 masing-masing.

Catatan

Parameter kueri tidak diperbolehkan dalam servers properti spesifikasi OpenAPI. Jika Anda mengekspor spesifikasi OpenAPI dari versi API, string kueri tidak akan muncul di URL server.

Versi asli

Jika Anda menambahkan versi ke API non-versi, versi Original akan dibuat secara otomatis dan akan merespons URL default, tanpa pengidentifikasi versi yang ditentukan. Versi Original memastikan bahwa pemanggil yang ada tidak rusak oleh proses penambahan versi. Jika Anda membuat API baru dengan versi yang diaktifkan di awal, versi Original tidak dibuat.

Bagaimana versi disajikan

Azure API Management mempertahankan sumber daya yang disebut kumpulan versi, yang menyajikan serangkaian versi untuk satu API logis. Kumpulan versi berisi nama tampilan API versi dan skema penerapan versi yang digunakan untuk mengarahkan permintaan ke versi tertentu.

Setiap versi API dipertahankan sebagai sumber daya API sendiri, yang kemudian dikaitkan dengan kumpulan versi. Kumpulan versi mungkin berisi API dengan operasi atau kebijakan yang berbeda. Anda mungkin membuat perubahan signifikan antar versi dalam satu kumpulan.

Portal Microsoft Azure membuat kumpulan versi untuk Anda. Anda dapat mengubah nama dan deskripsi untuk kumpulan versi di portal Microsoft Azure.

Set versi secara otomatis dihapus saat versi final dihapus.

Anda dapat melihat dan mengelola kumpulan versi secara langsung dengan menggunakan Azure CLI, Azure PowerShell, templat Resource Manager, atau API Azure Resource Manager.

Catatan

Semua versi dalam set versi memiliki skema penerapan versi yang sama, berdasarkan skema penerapan versi yang digunakan saat Anda pertama kali menambahkan versi ke API.

Melakukan migrasi API non-versi ke API versi

Saat Anda menggunakan portal Microsoft Azure untuk mengaktifkan penerapan versi pada API yang ada, perubahan berikut dilakukan ke sumber daya API Management Anda:

  • Kumpulan versi baru dibuat.
  • Versi yang ada dipertahankan dan dikonfigurasi sebagai versi API Original. API ditautkan ke kumpulan versi tetapi tidak memerlukan pengidentifikasi versi untuk ditentukan.
  • Versi baru dibuat sebagai API baru, dan ditautkan ke kumpulan versi. API baru ini harus diakses menggunakan skema penerapan versi dan pengidentifikasi.

Versi dan revisi

Versi dan revisi adalah fitur yang berbeda. Setiap versi dapat memiliki beberapa revisi, sama seperti API tak berversi. Anda dapat menggunakan revisi tanpa menggunakan versi, atau sebaliknya. Biasanya versi digunakan untuk memisahkan versi API dengan perubahan yang merusak (breaking change), sedangkan revisi dapat digunakan untuk perubahan kecil dan tidak merusak (non-breaking) pada API.

Jika Anda menemukan bahwa revisi Anda memiliki perubahan yang merusak (breaking change), atau jika Anda ingin mengubah revisi secara formal menjadi versi beta/tes, Anda dapat membuat versi dari revisi. Menggunakan portal Microsoft Azure, klik 'Buat Versi dari Revisi' pada menu konteks revisi pada tab Revisi.

Portal pengembang

Portal pengembang mencantumkan setiap versi API secara terpisah.

Portal pengembang API Management menampilkan daftar API versi

Detail API juga menampilkan daftar semua versi API tersebut. Versi Original ditampilkan tanpa pengidentifikasi versi.

Portal pengembang API Management menampilkan detail API dan daftar versi untuk API tersebut

Tip

Versi API perlu ditambahkan ke produk sebelum dapat terlihat di portal pengembang.