Versioning
Identification
API versioning adalah metode untuk memanajemen perubahan pada API. Ketika API membutuhkan perubahan sesuai dengan kebutuhan alur bisnis, teknologi baru, atau penyelesaian bug, developer harus berhati-hati ketika mengupdate source karena harus memastikan API versi sebelumnya tetap berjalan normal sembari mengembangkan fitur baru untuk versi selanjutnya.
Proses versioning API berguna untuk stabilitas dalam Ekosistem. Ekosistem ini membuat konsistensi ketika adanya perubahan fungsi API tanpa mengganggu aplikasi yang sedang berjalan.
Major Changes
Perubahan Major adalah perubahan yang mengubah struktur data, behaviour dan juga output dari endpoint. Update major ini artinya membuat API versi sebelumnya tidak kompitabel dengan versi yang baru. Dengan adanya perubahan major ini aplikasi yang terhubung harus menyesuaikan dengan merubah versi API dan menyesuaikan output dari endpoint.
Minor Changes
Perubahan Minor umumnya tidak berefek pada versi yang sedang berjalan sekarang. Kompitabilitas pada perubahan minor tidak menggangu aplikasi yang sedang menggunakan versi ini. Berikut adalah beberapa contoh perubahan minor :
- Menambahkan parameter baru yang bersifat opsional
- Menambahkan response data tanpa mengubah structure sebelumnya
URI Versioning
URI (Uniform Resource Identifier) Versioning adalah salah satu metode yang paling sering digunakan. Metode pembuatan versi API ini menggabungkan nomor versi langsung ke dalam URL. Biasanya, nomor versi mengakhiri URL dasar API dengan garis miring. Misalnya:
http://www.siniae.com/api/v1/products
Dengan menggunakan penomoran versi URI, pengembang dapat dengan mudah membedakan antara beberapa versi API dan mencegah konflik dengan aplikasi klien yang ada. Karena setiap versi API memiliki URI yang unik, mudah untuk menginstal beberapa versi API pada beberapa server atau environment.
Pengelolaan versi URI sangat ideal untuk API publik, di mana pengelolaan versi yang jelas dan kemudahan akses sangat penting bagi pengguna. Ini sempurna untuk API dengan beragam pengguna yang menginginkan manajemen versi yang jelas dan jalur pembaruan yang sederhana.
- Cara sederhana untuk menunjukkan versi API, memungkinkan pengembang untuk dengan mudah menentukan versi mana yang mereka gunakan.
- Kompatibel dengan pustaka atau alat klien HTTP apa pun karena hanya memerlukan pembuatan URL baru.
- Memungkinkan penerapan beberapa versi API dengan mudah ke server atau pengaturan yang berbeda.
- Hal ini dapat menyebabkan URL yang panjang dan berantakan, terutama jika terdapat banyak versi API.
- Perubahan pada struktur URL dapat menyebabkan masalah bagi program klien yang sudah ada, yang bergantung pada URL tersebut untuk mengakses sumber daya API.
Query Parameter Versioning
Query Parameter Versioning adalah metode pembuatan versi API di mana nomor versi API disertakan sebagai parameter query dalam URL. Versi tersebut diberikan sebagai bagian dari string query, bukan disertakan dalam rute URI. Klien dapat menentukan versi API yang ingin mereka gunakan dengan menambahkannya sebagai parameter dalam query. Misalnya:
http://www.example.com/api/products?version=1
Metode ini juga relatif mudah digunakan dan tidak mengharuskan Anda untuk memperbarui versi semua URI Anda sekaligus. Selain itu, beralih ke versi baru atas permintaan klien juga mudah. Jika klien tidak menyertakan nomor versi dalam permintaannya, Anda dapat menggunakan versi terbaru secara default.
- Memastikan URI yang konstan untuk sumber daya, yang akan menarik bagi pendukung REST yang menginginkan lebih sedikit perubahan pada URI.
- Pengguna dapat mengubah nomor versi di dalam string kueri tanpa mengubah URI, yang menyederhanakan pengujian dan peralihan versi.
- Versi tersebut merupakan bagian dari string kueri; oleh karena itu, pengguna mungkin merasa hal ini kurang jelas dan dapat menyebabkan kebingungan.
- Penggunaan versi yang berbeda di seluruh parameter kueri dapat menambah kompleksitas dalam mengidentifikasi versi default atau mengelola konflik versi tanpa persiapan yang cermat.
Header Versioning
Pengelolaan versi header adalah pengelolaan versi API di mana header permintaan menyertakan nomor versi. Dalam metode ini, nomor versi tidak disertakan dalam URL tetapi dalam header khusus, seperti 'Api-Version,' yang dikirimkan bersama permintaan. Setelah membaca header, server memilih versi API mana yang akan diterapkan untuk permintaan tersebut. Misalnya:
GET /users HTTP/1.1
host: api.example.com
api-version: 1
Pengembang dapat menggunakan pembuatan versi header untuk membuat permintaan ke URL yang sama dan meminta server merespons dengan versi API yang sesuai. Pembuatan versi tetap dimungkinkan sambil membantu menyederhanakan URL dan meningkatkan keterbacaannya. Selain itu, karena pendekatan ini tidak bergantung pada struktur URL, hal ini dapat membuat pengelolaan dan modifikasi menjadi lebih sederhana.
- Memberikan fleksibilitas yang lebih besar dalam pembuatan versi API, karena teknik pembuatan versi yang berbeda dapat digunakan untuk sumber daya yang berbeda.
- Lebih mudah untuk menambahkan atau memodifikasi skema pembuatan versi karena struktur URL tidak perlu diubah.
- Karena nomor versi tidak terdapat dalam URL, maka akan lebih mudah untuk menerapkan dan mengelola caching atau penanganan melalui proxy.
- Diperlukan perubahan pada kode klien untuk menyertakan header kustom atau header Accept.
- Proses debugging bisa lebih sulit karena informasi versi tidak tersedia di URL.
- Implementasinya bisa lebih sulit karena melibatkan perubahan pada kode server untuk membaca header dan mengarahkan permintaan dengan tepat.
Changelog
Catat setiap perubahan dalam changelog. Contoh pencatatan changelog
Updates
- Add package google api
- Add google login
Updates
- Repair label log_in to login
- Add error code "INACTIVE_USER" for user is_active = 0
- Add validation is_active to user login