Cara menjadikan API REST anda serasi ke belakang

Perpindahan Negara Perwakilan, yang biasanya dikenal sebagai REST, adalah gaya seni bina — sekumpulan batasan yang digunakan untuk melaksanakan perkhidmatan tanpa status yang berjalan di HTTP. API RESTful adalah yang sesuai dengan batasan REST. Anda boleh membina API RESTful menggunakan banyak bahasa pengaturcaraan yang berbeza.

Mempertahankan keserasian ke belakang antara pelepasan yang berbeza dari API anda adalah sangat penting dalam memastikan bahawa API anda akan tetap serasi dengan semua klien yang menggunakannya. Artikel ini memaparkan perbincangan mengenai bagaimana anda dapat mengekalkan keserasian ke belakang dalam API RESTful anda.

Contoh keserasian API

Andaikan bahawa anda mempunyai API dalam pengeluaran yang digunakan oleh pelanggan yang berbeza. Sekarang jika anda ingin menambahkan lebih banyak fungsi ke API, anda harus memastikan bahawa klien yang menggunakan API lama akan dapat menggunakan API baru atau yang lama. Dengan kata lain, anda harus memastikan bahawa fungsi API yang ada akan tetap utuh semasa fungsi baru ditambahkan.

API serasi ke belakang jika klien (program yang ditulis untuk menggunakan API) yang dapat berfungsi dengan satu versi API dapat berfungsi dengan cara yang sama dengan versi API yang akan datang. Dengan kata lain, API serasi ke belakang antara pelepasan jika pelanggan seharusnya dapat bekerja dengan versi baru API dengan lancar.

Mari kita fahami ini dengan contoh. Andaikan bahawa anda mempunyai kaedah API bernama GetOrders seperti yang ditunjukkan dalam coretan kod di bawah.

[HttpGet]

[Laluan ("GetOrders")]

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

 {

   var result = _orderService.GetOrdersForCustomer (

                 customerId, orderId);

   kembali Ok (hasil);

 }

Kaedah tindakan GetOrders menerima ID pelanggan dan ID pesanan sebagai parameter. Perhatikan bahawa parameter kedua, orderID, adalah pilihan. Kaedah peribadi GetOrdersForCustomer diberikan di bawah.

senarai peribadi GetOrdersForCustomer (int customerId, int orderId)

{

   // Tulis kod di sini untuk mengembalikan satu atau beberapa rekod pesanan

}

Kaedah GetOrdersForCustomer mengembalikan semua pesanan pelanggan jika orderId diteruskan kepadanya sebagai parameter adalah 0. Jika orderId tidak sifar, ia mengembalikan satu pesanan yang berkaitan dengan pelanggan yang dikenalpasti oleh customerId yang disampaikan sebagai argumen.

Oleh kerana parameter kedua kaedah tindakan GetOrders adalah pilihan, anda boleh meneruskan customerId. Sekarang, jika anda mengubah parameter kedua kaedah tindakan GetOrders untuk menjadikannya wajib, klien lama API tidak akan dapat menggunakan API lagi.  

[HttpGet]

[Laluan ("GetOrders")]

 awam IActionResult GetOrders (int customerId, int orderId)

 {

   var result = _orderService.GetOrdersForCustomer

                 (customerId, orderId);

   kembali Ok (hasil);

 }

Dan, itulah cara anda memecahkan keserasian API anda! Bahagian yang berikut membincangkan amalan terbaik yang boleh digunakan untuk menjadikan API anda serasi dengan belakang.

Petua keserasian API

Sekarang setelah kita mengetahui masalahnya, bagaimana kita merancang API dengan cara yang disyorkan? Bagaimana kita memastikan bahawa API RESTful kami serasi ke belakang? Bahagian ini menyenaraikan beberapa amalan terbaik yang boleh diikuti dalam hal ini. 

Pastikan ujian unit lulus

Anda harus mempunyai ujian yang ditulis yang akan mengesahkan apakah fungsi tersebut masih utuh dengan pelepasan baru API. Ujian yang harus ditulis adalah sedemikian rupa sehingga mereka gagal sekiranya terdapat masalah keserasian ke belakang. Sebaik-baiknya anda harus mempunyai rangkaian ujian untuk pengujian API yang akan gagal dan waspada apabila terdapat masalah dengan keserasian API yang mundur. Anda juga mungkin mempunyai rangkaian uji automatik yang terpasang ke saluran paip CI / CD yang memeriksa keserasian dan peringatan ke belakang apabila ada pelanggaran.

Jangan sekali-kali mengubah tingkah laku kod respons HTTP

Anda tidak boleh mengubah tingkah laku kod respons HTTP di API anda. Sekiranya API anda mengembalikan 500 apabila gagal menyambung ke pangkalan data, anda tidak boleh mengubahnya menjadi 200. Begitu juga, jika anda mengembalikan HTTP 404 ketika pengecualian berlaku, dan pelanggan anda menggunakan ini dan objek respons untuk mengenal pasti apa yang berlaku salah, mengubah kaedah API ini untuk mengembalikan HTTP 200 akan memecahkan keserasian ke belakang sama sekali.

Jangan sekali-kali menukar parameter

Elakkan membuat versi baru API apabila anda hanya membuat perubahan kecil, kerana mungkin berlebihan. Pendekatan yang lebih baik adalah menambahkan parameter ke kaedah API anda untuk memasukkan tingkah laku baru. Dengan cara yang sama, anda tidak boleh membuang parameter dari kaedah API atau mengubah parameter dari pilihan menjadi wajib (atau sebaliknya), kerana perubahan ini akan mematahkan API dan klien lama atau pengguna API tidak akan dapat lagi untuk bekerja dengan API.

Versi API anda

Versi API adalah amalan yang baik. Versi menolong menjadikan API anda lebih fleksibel dan dapat disesuaikan dengan perubahan sambil menjaga fungsi tetap utuh. Ini juga membantu anda mengurus perubahan kod dengan lebih baik dan lebih mudah kembali ke kod lama jika kod baru menyebabkan masalah. Anda harus mempunyai versi RESTful API yang berbeza dengan setiap rilis utama.

Walaupun REST tidak memberikan panduan khusus mengenai pembuatan versi API, Anda dapat membuat versi API dengan tiga cara yang berbeda: menentukan maklumat versi dalam URI, menyimpan maklumat versi dalam tajuk permintaan khusus, dan menambahkan informasi versi ke HTTP Terima kepala. Walaupun versi dapat menolong anda mengekalkan API anda, anda harus menghindari berusaha mempertahankan banyak versi API untuk menandakan pelepasan yang kerap. Ini akan menjadi tidak praktikal dan tidak produktif. 

Amalan terbaik API lain

Anda tidak boleh mengubah URL root API atau mengubah parameter rentetan pertanyaan yang ada. Sebarang maklumat tambahan harus ditambahkan sebagai parameter pilihan untuk kaedah API. Anda juga harus memastikan bahawa elemen pilihan atau wajib yang dihantar ke API atau dikembalikan dari API tidak akan dihapuskan.

Perubahan pada API RESTful tidak dapat dielakkan. Namun, melainkan jika anda mematuhi amalan terbaik dan memastikan bahawa API serasi dengan kebelakangan, perubahan anda dapat memecahkan keserasian API dengan klien yang ada. API yang sedang dalam pengeluaran dan digunakan oleh banyak pelanggan harus selalu serasi antara pengeluaran.