Cara membuat REST API Anda kompatibel ke belakang

Representational State Transfer, biasanya dikenal sebagai REST, adalah gaya arsitektur — sekumpulan batasan yang digunakan untuk mengimplementasikan layanan stateless yang berjalan di HTTP. RESTful API adalah salah satu yang sesuai dengan batasan REST. Anda dapat membangun RESTful API menggunakan berbagai bahasa pemrograman.

Mempertahankan kompatibilitas mundur antara berbagai rilis API Anda sangat penting untuk memastikan bahwa API Anda akan tetap kompatibel dengan semua klien yang mengonsumsinya. Artikel ini menyajikan diskusi tentang bagaimana Anda bisa mempertahankan kompatibilitas ke belakang di RESTful API Anda.

Contoh kompatibilitas API

Asumsikan bahwa Anda memiliki API dalam produksi yang digunakan oleh klien yang berbeda. Sekarang jika Anda ingin menambahkan lebih banyak fungsionalitas ke API, Anda harus memastikan bahwa klien yang menggunakan API lama akan dapat menggunakan API baru atau yang lama. Dengan kata lain, Anda harus memastikan bahwa fungsionalitas API yang ada akan tetap utuh saat fungsionalitas baru ditambahkan.

API kompatibel ke belakang jika klien (program yang ditulis untuk menggunakan API) yang dapat bekerja dengan satu versi API dapat bekerja dengan cara yang sama dengan versi API yang akan datang. Dengan kata lain, API kompatibel dengan rilis sebelumnya jika klien harus dapat bekerja dengan versi baru API dengan lancar.

Mari kita pahami ini dengan sebuah contoh. Asumsikan bahwa Anda memiliki metode API bernama GetOrders seperti yang ditunjukkan dalam cuplikan kode di bawah ini.

[HttpGet]

[Rute ("GetOrders")]

 publik IActionResult GetOrders (int customerId, int orderId = 0)

 {

   var result = _orderService.GetOrdersForCustomer (

                 customerId, orderId);

   return Ok (hasil);

 }

Metode tindakan GetOrders menerima ID pelanggan dan ID pesanan sebagai parameter. Perhatikan bahwa parameter kedua, orderID, adalah opsional. Metode pribadi GetOrdersForCustomer diberikan di bawah ini.

Private List GetOrdersForCustomer (int customerId, int orderId)

{

   // Tulis kode di sini untuk mengembalikan satu atau lebih catatan pesanan

}

Metode GetOrdersForCustomer mengembalikan semua pesanan pelanggan jika orderId yang diteruskan ke sana sebagai parameter adalah 0. Jika orderId bukan nol, ia mengembalikan satu pesanan yang berkaitan dengan pelanggan yang diidentifikasi oleh customerId yang diteruskan sebagai argumen.

Karena parameter kedua dari metode tindakan GetOrders adalah opsional, Anda cukup meneruskan customerId. Sekarang, jika Anda mengubah parameter kedua dari metode tindakan GetOrders menjadi wajib, klien lama API tidak akan dapat menggunakan API lagi.  

[HttpGet]

[Rute ("GetOrders")]

 publik IActionResult GetOrders (int customerId, int orderId)

 {

   var result = _orderService.GetOrdersForCustomer

                 (customerId, orderId);

   return Ok (hasil);

 }

Dan, itulah cara Anda dapat merusak kompatibilitas API Anda! Bagian selanjutnya membahas praktik terbaik yang dapat diterapkan untuk membuat API Anda kompatibel dengan versi sebelumnya.

Tips kompatibilitas API

Sekarang kita tahu apa masalahnya, bagaimana kita mendesain API kita dengan cara yang disarankan? Bagaimana kami memastikan bahwa RESTful API kami kompatibel dengan versi sebelumnya? Bagian ini mencantumkan beberapa praktik terbaik yang dapat diikuti dalam hal ini. 

Pastikan tes unit lulus

Anda harus memiliki tes tertulis yang akan memverifikasi apakah fungsionalitas tersebut utuh dengan rilis baru API. Tes harus ditulis sedemikian rupa sehingga harus gagal jika ada masalah kompatibilitas ke belakang. Idealnya, Anda harus memiliki rangkaian pengujian untuk pengujian API yang akan gagal dan memberi peringatan jika ada masalah dengan kompatibilitas API sebelumnya. Anda juga dapat memasang rangkaian pengujian otomatis ke pipeline CI / CD yang memeriksa kompatibilitas mundur dan peringatan jika ada pelanggaran.

Jangan pernah mengubah perilaku kode respons HTTP

Anda tidak boleh mengubah perilaku kode respons HTTP di API Anda. Jika API Anda mengembalikan 500 saat gagal terhubung ke database, Anda tidak boleh mengubahnya menjadi 200. Demikian pula, jika Anda mengembalikan HTTP 404 saat terjadi pengecualian, dan klien Anda menggunakan ini dan objek respons untuk mengidentifikasi apa yang terjadi. salah, mengubah metode API ini untuk mengembalikan HTTP 200 akan merusak kompatibilitas mundur sama sekali.

Jangan pernah mengubah parameter

Hindari membuat versi baru API jika Anda hanya membuat perubahan kecil, karena mungkin berlebihan. Pendekatan yang lebih baik adalah dengan menambahkan parameter ke metode API Anda untuk memasukkan perilaku baru. Dengan token yang sama, Anda tidak boleh menghapus parameter dari metode API atau mengubah parameter dari opsional menjadi wajib (atau sebaliknya), karena perubahan ini akan merusak API dan klien lama atau konsumen API tidak akan dapat lagi untuk bekerja dengan API.

Versi API Anda

Pembuatan versi API adalah praktik yang baik. Pembuatan versi membantu membuat API Anda lebih fleksibel dan mudah beradaptasi dengan perubahan sekaligus menjaga fungsionalitasnya tetap utuh. Ini juga membantu Anda mengelola perubahan pada kode dengan lebih baik dan lebih mudah kembali ke kode lama jika kode baru menyebabkan masalah. Anda harus memiliki versi berbeda dari RESTful API Anda dengan setiap rilis utama.

Meskipun REST tidak memberikan panduan khusus apa pun tentang pembuatan versi API, Anda dapat membuat versi API Anda dengan tiga cara berbeda: menentukan informasi versi di URI, menyimpan informasi versi di header permintaan khusus, dan menambahkan informasi pembuatan versi ke HTTP Terima header. Meskipun pembuatan versi dapat membantu Anda mempertahankan API, Anda harus menghindari mencoba mempertahankan banyak versi API untuk menandai rilis yang sering. Ini akan dengan cepat menjadi tidak praktis dan kontraproduktif. 

Praktik terbaik API lainnya

Anda tidak boleh mengubah URL root dari API atau mengubah parameter string kueri yang ada. Informasi tambahan apa pun harus ditambahkan sebagai parameter opsional untuk metode API. Anda juga harus memastikan bahwa elemen opsional atau wajib yang diteruskan ke API atau dikembalikan dari API tidak pernah dihapus.

Perubahan pada RESTful API tidak bisa dihindari. Namun, kecuali Anda mematuhi praktik terbaik dan memastikan bahwa API kompatibel dengan versi sebelumnya, perubahan Anda dapat merusak kompatibilitas API dengan klien yang ada. API yang sedang diproduksi dan digunakan oleh banyak klien harus selalu kompatibel dengan rilis sebelumnya.