API REST Versioning. Setiap API memiliki versinya sendiri

Sangat umum untuk menentukan versi REST API di URL, khususnya di awal jalur, yaitu sesuatu seperti:

POST /api/v1/accounts
GET /api/v1/accounts/details

Namun, saya belum melihat desain di mana versi dikaitkan dengan setiap API. Dengan kata lain, kami mempertahankan versi setiap API secara terpisah. yaitu:

POST /api/accounts/v2
GET /api/accounts/details/v3

Dengan menggunakan pendekatan ini, kami menambah versi API dari API tertentu saat memecah perubahan diperlukan, tidak perlu menambah versi seluruh API.

Apa kelemahan menggunakan gaya ini dan bukan gaya umum?

Apa yang Anda sebut REST API tunggal mungkin disebut set sumber daya atau sumber daya REST API tertentu . Anda juga dapat melihatnya sebagai fungsionalitas REST API . Seperti segala jenis perangkat lunak, seluruh paket diversi / diperbarui, bukan fungsi tunggal atau sumber daya.

Pertanyaan Anda akan masuk akal dalam konteks di mana sumber daya paket REST API bersifat modular dan berpotensi dikembangkan dan diversi secara terpisah.

Kemudian, sejauh yang saya lihat, kontra utama dari konvensi penamaan pencari sumber daya yang Anda usulkan adalah:

• Untuk pengguna API , ini akan menghasilkan pencari sumber daya yang jauh lebih kompleks, kurang dapat diprediksi, kurang mudah diingat dan kurang stabil.
• Untuk pengembang modul , sekarang lebih banyak pekerjaan harus berurusan dengan versi ini di pencari sumber daya mereka sendiri .
• Perubahan pencari sumber daya menjadi jauh lebih sering, sebanyak ada beberapa modul yang diperbarui sehingga kontra di atas bersifat eksponensial ...

Saat membuat API, salah satu tujuan utama Anda adalah membuatnya mudah digunakan ...

Anda mungkin menemukan cara yang lebih baik untuk memperkenalkan perubahan yang melanggar atau bahkan versi REST API dengan mungkin header HTTP?

Untuk mengetahui lebih banyak tentang pendekatan HTTP header, lihat jawaban lain di bawah ini dan: https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

Inilah pendekatan yang lebih baik: gunakan negosiasi konten untuk versi API Anda dengan Content-Typedan Acceptheader:

POST /api/accounts
Accept: application/vnd.my-api.account.v1+json

201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }

Untuk mendapatkan versi yang berbeda, minta saja dengan tipe konten yang berbeda di Accept. Dengan cara ini, versi tertentu yang didukung server Anda sepenuhnya independen dari struktur URL Anda. Server yang sama dapat mendukung banyak versi hanya dengan memilih yang akan ditanggapi berdasarkan Acceptheader. Atau, jika Anda ingin tetap menggunakan penyebaran yang berbeda untuk versi yang berbeda, Anda bisa meletakkan proxy di depan versi layanan Anda yang berbeda yang memilih permintaan mana yang akan diteruskan berdasarkan pada Acceptheader.

Ini juga memungkinkan Anda mendukung format baru dengan semantik berbeda (bukan hanya versi berbeda) pada titik akhir yang sama. Misalnya, POSTing daftar akun /api/accountsdapat berarti pembuatan batch, dan Anda tidak perlu membuat titik akhir API terpisah untuk itu.

Kuncinya adalah bahwa jika Anda membuat versi setiap titik akhir secara terpisah, maka Anda harus dapat menggunakan setiap titik akhir secara terpisah.

API biasanya memiliki satu versi karena semua titik akhir berada dalam basis kode yang sama dan karenanya memiliki dependensi bersama dan digunakan bersama.

Jika Anda tidak memperbarui versi ketika Anda membuat perubahan karena "Oh, saya cukup yakin perubahan saya tidak mempengaruhi itu" baik Anda akan mendapat masalah ketika Anda membuat kesalahan.

Selain itu, Anda ingin memiliki v1 dan v2 API Anda digunakan pada saat yang sama. Ini biasanya dilakukan dengan menempatkan setiap versi ke server terpisah dan merutekan lalu lintas sesuai.

Jika Anda tidak memiliki versi API tunggal ini menjadi jauh lebih kompleks.