Apa kode status HTTP yang benar untuk: "Versi API ini telah dihentikan"?

Saya memiliki API yang tenang. Ada 3 versi: v1, v2, dan v3. Saya akan menerbitkan v4, dan kami telah memutuskan untuk menghentikan v1, yang berarti bahwa semua permintaan http://example.com/v1/resourceakan gagal, tetapi panggilan untuk http://example.com/v2/resourceakan terus bekerja.

Apa cara yang tepat untuk menunjukkan kegagalan? Saya mempertimbangkan untuk menggunakan 410 GONEkode status, tetapi itu menunjukkan bahwa sumber daya tidak lagi tersedia. Sumber daya kemungkinan IS masih tersedia, namun, hanya itu harus diminta dengan cara yang berbeda.

Saya juga menganggap 400kode status umum , tetapi itu juga terasa aneh. Apakah ada jawaban standar untuk ini?

Sepertinya tidak ada standar.

Jawaban StackOverflow condong ke arah 410 GONE, tapi saya pikir 301 PINDAH PERMANEN lebih tepat.

Untuk membuat pilihan yang benar, kami harus melihat kasus spesifik Anda. Jika tujuan Anda adalah membuat semua panggilan ke API v1 gagal tanpa mengambil tindakan lebih lanjut, 410 GONE bekerja untuk itu. Jika Anda menginginkan kontinuitas, seperti mengarahkan ulang klien ke versi API Anda yang lebih baru di mana panggilan mereka dapat berhasil, 3XX berfungsi, tetapi mana yang Anda pilih? Saya pikir jika Anda mencoba untuk mematikan API v1, 301 PINDAH PERMANEN membantu menunjukkan bahwa lebih baik dari 303 MELIHAT LAINNYA karena 301 menyarankan bahwa semua permintaan di masa mendatang harus dilakukan ke url baru sedangkan 303 tidak menunjukkan apakah situasi ini atau tidak. permanen.

Saya akan merekomendasikan rekayasa API sedemikian rupa sehingga setiap versi tetap kompatibel ke belakang, sehingga 301 PINDAH SECARA PERMANEN akan secara transparan menjaga API Anda tetap hidup dan mutakhir setiap kali Anda menambahkan titik akhir baru untuk versi API baru. Saya pikir itulah yang Anda coba lakukan.

Kode Status HTTP

Kode status HTTP 302 pada awalnya terlalu luas dan dengan demikian menjadi salah diterapkan / digunakan, jadi 303 dan 307 dibuat untuk membedakan antara kasus penggunaan ganda 302. Beberapa API menggunakan 303 untuk tujuan lain.

301 PINDAHKAN SECARA PERMANEN - Kode status 301 (Dipindahkan Secara Permanen) menunjukkan bahwa sumber daya target telah diberi URI permanen baru dan setiap referensi di masa mendatang untuk sumber daya ini harus menggunakan salah satu URI terlampir.

302 DITEMUKAN - Kode status 302 (Ditemukan) menunjukkan bahwa sumber daya target sementara berada di bawah URI yang berbeda. Karena pengalihan mungkin kadang-kadang diubah, klien harus terus menggunakan URI permintaan efektif untuk permintaan di masa mendatang.

303 LIHAT LAINNYA - Respons 303 untuk permintaan GET menunjukkan bahwa server asal tidak memiliki representasi sumber daya target yang dapat ditransfer oleh server melalui HTTP. Namun, nilai bidang Lokasi merujuk pada sumber daya yang deskriptif dari sumber daya target, sehingga membuat permintaan pengambilan sumber daya lain dapat menghasilkan representasi yang berguna bagi penerima tanpa menyiratkan bahwa itu mewakili sumber daya target asli.

410 GONE - Kode status 410 (Hilang) menunjukkan bahwa akses ke sumber daya target tidak lagi tersedia di server asal dan bahwa kondisi ini cenderung permanen. Jika server asal tidak tahu, atau tidak memiliki fasilitas untuk menentukan, apakah kondisinya permanen atau tidak, kode status 404 (Tidak Ditemukan) harus digunakan sebagai gantinya.

Bagaimana API yang ada menangani ini?

Mungkin Anda dapat mengambil halaman dari API Youtube Google :

Ketika permintaan API gagal, YouTube akan mengembalikan kode respons HTTP 4xx atau 5xx yang secara umum mengidentifikasi kegagalan serta respons XML yang memberikan informasi lebih spesifik tentang kesalahan yang menyebabkan kegagalan tersebut. Untuk setiap kesalahan, respons XML mencakup elemen domain, elemen kode, dan mungkin elemen lokasi.

• API BigCommerce menggunakan 302 DITEMUKAN.
• Petunjuk API Atlassian REST mengisyaratkan 301 MOVED PERMANENTLY bersama dengan sub-kode yang menjelaskan kesalahan secara rinci. Ini mirip dengan pendekatan Youtube API.

Bacaan lebih lanjut:

• Bagaimana versi REST API diversi?
• Netflix API Design: Kapan Harus Menambah Tren

Pengalihan sangat bagus untuk sumber daya yang telah pindah. Alih-alih 301 redirect permanen (yang akan menunjukkan nama baru tanpa perubahan API), saya akan menggunakan 303 redirect "Lihat Lainnya".

Perlu tetap mendukung warisan tanpa pengalihan? Bahkan jika Anda masih mendukungnya dan jauh di lubuk hati masih diterapkan, 501 tampaknya agak sejalan dengan situasi Anda. Mereka yang tahu masih bisa menggunakannya, sementara tebusan akan melihat 501 untuk v1.

10.5.2 501 Tidak Diimplementasikan

Server tidak mendukung fungsi yang diperlukan untuk memenuhi permintaan. Ini adalah respons yang sesuai ketika server tidak mengenali metode permintaan dan tidak mampu mendukungnya untuk sumber daya apa pun.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Saya akan menggunakan 503 dengan pesan bahwa layanan tidak tersedia dan menunjukkan untuk menggunakan versi yang lebih baru. Pesan ini dapat dikembalikan untuk 50% panggilan dan pada waktunya secara bertahap meningkat menjadi 100%.

Untuk migrasi transparan, saya akan menggunakan 308 - Pengalihan Permanen, karena metode ini tidak mengubah kata kerja (POST akan POST) tidak seperti 301.