Cara Mencegah Perubahan API yang Merusak dengan API Gateway
September 11, 2023
Ketika Anda mengembangkan API, terkadang Anda melakukan perubahan yang mungkin menyebabkan masalah bagi konsumen API saat ini. Mengembangkan API Anda tanpa memengaruhi pengguna saat ini sangat penting, jika tidak, mereka mungkin kehilangan kepercayaan pada penawaran Anda. Tidak mungkin untuk sepenuhnya menghindari masalah ini, tetapi Anda dapat meminimalkan dampaknya atau menangkap beberapa perubahan yang merusak sebelum terjadi. Perubahan yang merusak perlu diidentifikasi selama fase pengembangan, dan jika terjadi, API gateway harus menanganinya untuk memastikan aplikasi klien tetap tidak terpengaruh. Dalam artikel ini, kita akan menjelajahi beberapa praktik terbaik dan strategi untuk mencegah perubahan yang merusak API dan bagaimana menanganinya menggunakan APISIX API Gateway.
Apa itu perubahan yang merusak API?
Produk perangkat lunak berkembang secara konsisten, dan API mereka tidak terkecuali. API ini berfungsi sebagai antarmuka utama di mana konsumen API eksternal berinteraksi dengan sistem Anda, mencerminkan setiap perubahan produk. Ada berbagai alasan untuk modifikasi API ini, termasuk peningkatan teknologi, perubahan arah bisnis, perbaikan bug kritis, dan lainnya. Secara sederhana, breaking change adalah ketika Anda mengubah API Anda dan itu mungkin menyebabkan masalah bagi aplikasi klien yang menggunakannya. Beberapa perubahan ini lebih mudah dikenali daripada yang lain. Berikut adalah beberapa contoh perubahan yang merusak:
- Menghapus Endpoint: Jika Anda memiliki endpoint
GET /usersdan memutuskan untuk menghapusnya, setiap klien yang mencoba mengaksesnya akan menerima error. - Mengubah URL Endpoint: Jika Anda mengubah URL endpoint dari
GET /userskeGET /members, setiap klien yang menggunakan URL lama akan menghadapi masalah. - Memodifikasi Payload Request: Jika sebuah endpoint mengharapkan data tertentu dalam request, seperti
POST /usersyang mengharapkan{ "name": "John" }, tetapi Anda mengubah persyaratan menjadi{ "firstName": "John" }, ini akan mengganggu klien yang mengirim format lama. - Menghapus atau Mengganti Nama Field dalam Response: Jika klien mengharapkan field tertentu dalam respons API, menghapus atau mengganti nama mereka akan menyebabkan klien tersebut tidak berfungsi. Misalnya, mengubah
{ "id": 1, "name": "John" }menjadi{ "id": 1, "fullName": "John Doe" }. - Mengubah Tipe Data: Jika sebuah field API diharapkan menjadi string dan Anda mengubahnya menjadi integer atau tipe lain, ini dapat merusak klien. Misalnya, mengubah
"age": "25"menjadi"age": 25. - Mengubah Mekanisme Autentikasi: Jika Anda beralih dari autentikasi dasar ke autentikasi berbasis token tanpa transisi yang tepat, klien yang ada akan menghadapi error autentikasi.
- Memperkenalkan Field Wajib: Jika Anda memiliki endpoint seperti
POST /usersyang menerima field opsional, dan Anda tiba-tiba membuat salah satu field tersebut wajib, klien yang ada yang tidak mengirim field tersebut akan menghadapi masalah. - Mengubah Format Error: Jika klien diprogram untuk memahami format error tertentu, mengubah format tersebut dapat menyebabkan penanganan error yang tidak tepat di sisi klien.
- Memodifikasi Kode Status HTTP: Mengubah kode status untuk operasi tertentu, seperti mengembalikan
200 OKalih-alih201 Createduntuk pembuatan sumber daya, dapat menyesatkan klien. - Menghentikan Dukungan untuk Versi API Lama: Jika Anda menghentikan dukungan untuk versi lama tanpa periode transisi yang tepat, klien yang mengandalkan versi lama tersebut akan rusak.
Setiap perubahan dalam API berpotensi merusak aplikasi klien. Jika Anda menggunakan API Gateway seperti pintu depan untuk semua API backend, gateway tahu ke mana harus meneruskan permintaan berdasarkan seperangkat aturan yang ditentukan dalam konfigurasi rute dan itu adalah tempat yang tepat untuk menangani perubahan API yang merusak. Mari kita lihat bagaimana kita dapat menggunakan APISIX untuk mengidentifikasi beberapa perubahan API.
Validasi skema request & response
Mendefinisikan skema yang ketat untuk rute Anda memungkinkan Anda memastikan struktur request dan response sesuai dengan yang diharapkan. Gunakan plugin request-validation untuk memvalidasi request yang masuk dan plugin response-rewrite untuk menulis ulang respons API berdasarkan kondisi tertentu.
Logging
APISIX mendukung berbagai plugin logging, seperti http-logger, elasticsearch-logger, file-logger, dan lainnya. Siapkan logger untuk menyimpan data request dan respons API dan analisis log secara teratur untuk mendeteksi perubahan dalam header request/respons, struktur payload, atau pola yang tidak biasa lainnya.
Pemantauan rute dan upstream
Pantau rute yang melewati gateway. Jika rute yang sebelumnya tersedia tiba-tiba mulai mengembalikan error 404, itu adalah tanda potensial bahwa API telah mengalami perubahan atau endpoint telah dihentikan. Aktifkan fitur API health check untuk memantau secara terus-menerus kesehatan keseluruhan node upstream. Jika salah satu node mulai gagal, merespons lebih cepat atau lebih lambat dari biasanya, itu mungkin menunjukkan perubahan dalam pemrosesan layanan backend yang mendasar. Integrasikan APISIX dengan alat pemantauan seperti Prometheus menggunakan plugin prometheus. Siapkan peringatan berdasarkan metrik, seperti peningkatan tingkat error 4xx atau 5xx, yang dapat menunjukkan perubahan yang merusak dalam API Anda.
Menggunakan versioning
API versioning adalah praktik mengelola perubahan pada API dan memastikan bahwa perubahan ini dilakukan tanpa mengganggu aplikasi konsumen API. Ada berbagai metode untuk menyiapkan versioning dengan APISIX, seperti menggunakan jalur URI, parameter query, header, atau memilih tipe konten. Misalnya, Anda mungkin memiliki alamat web seperti /v1/users atau /v2/users untuk menunjukkan versi API Anda. Dengan memiliki versi ini, Anda dapat menawarkan lebih dari satu opsi API Anda, memungkinkan konsumen API untuk memutuskan kapan harus meningkatkan ke versi terbaru sesuai kecepatan mereka sendiri. APISIX dapat dengan mudah mengarahkan semua lalu lintas kembali ke versi API lama yang stabil sampai Anda menangani masalah dalam versi baru yang membuat API Anda backward-compatible. Gunakan APISIX untuk mempertahankan kompatibilitas lama sambil meluncurkan perubahan baru jika Anda mendeteksi masalah dalam versi baru, plugin traffic-split memungkinkan rollback cepat.
Pemberitahuan deprecation
Sebelum menghapus atau mengubah fitur, tandai mereka sebagai deprecated, memberikan konsumen waktu yang cukup untuk beradaptasi. Dengan bantuan APISIX, kita dapat mengonfigurasi rute untuk mengomunikasikan tentang deprecation di masa depan dan penggantinya. Untuk itu, APISIX menawarkan plugin response-rewrite.
Integrasi dengan kontrol versi
Meskipun Anda mungkin berharap bahwa peninjau pull request akan menemukan perubahan yang merusak, mengandalkan metode ini saja tidak pasti dan mungkin menyebabkan kegagalan pada akhirnya. Jika Anda memiliki dokumentasi OpenAPI/Swagger untuk API Anda, ini dapat dikontrol versi dan dimasukkan dalam pipeline CI. APISIX tidak secara native mendukung integrasi langsung dengan sistem kontrol versi seperti Git untuk perubahan spesifikasi API. Namun, Anda dapat menyiapkan proses di luar APISIX. Alat seperti Oasdiff atau Bump dapat mengidentifikasi perubahan dalam spesifikasi API, dan memicu pipeline CI (tambahkan GitHub Action) yang menjalankan tes terhadap endpoint rute di APISIX untuk memastikan tidak ada perubahan yang merusak yang diperkenalkan.
Cara lain untuk mendeteksi perubahan
Postman berisi template untuk secara otomatis memeriksa versi saat ini dari API Anda untuk perubahan yang merusak dan menjelaskan cara kerjanya dalam artikel ini. Anda dapat menambahkan detektor ke pipeline CI sebagai langkah tambahan. Setiap kali pipeline Anda dijalankan, detektor perubahan yang merusak akan menganalisis spesifikasi API saat ini terhadap yang sebelumnya dan memberi tahu Anda tentang perbedaan apa pun. Tergantung pada stack pengembangan Anda, ada pustaka lain untuk membandingkan spesifikasi OpenAPI. Artikel ini menjelaskan dengan baik bagaimana menangkapnya dalam praktik menggunakan strategi deployment yang diuji sebelum membawa perubahan baru ke produksi.
Ringkasan
Mendeteksi dan mencegah perubahan API yang merusak penting untuk mempertahankan kepercayaan dengan konsumen API dan memastikan kesuksesan layanan Anda. Dengan mengintegrasikan kemampuan APISIX seperti validasi request, versioning, logging, pemantauan, dan peringatan dengan teknik seperti pengujian kontrak API otomatis, Anda dapat memastikan API Anda berkembang tanpa memengaruhi klien Anda secara negatif.