REST API error mengembalikan praktik yang baik [ditutup]

Saya mencari panduan tentang praktik yang baik untuk mengembalikan kesalahan dari REST API. Saya sedang mengerjakan API baru sehingga saya bisa mengambil arah apa pun sekarang. Jenis konten saya adalah XML saat ini, tetapi saya berencana untuk mendukung JSON di masa depan.

Saya sekarang menambahkan beberapa kasus kesalahan, seperti misalnya klien mencoba menambahkan sumber daya baru tetapi telah melebihi kuota penyimpanannya. Saya sudah menangani kasus kesalahan tertentu dengan kode status HTTP (401 untuk otentikasi, 403 untuk otorisasi dan 404 untuk URI permintaan buruk). Saya melihat-lihat kode kesalahan HTTP yang diberkati, tetapi tak satu pun dari kisaran 400-417 yang tampaknya benar untuk melaporkan kesalahan spesifik aplikasi. Jadi pada awalnya saya tergoda untuk mengembalikan kesalahan aplikasi saya dengan 200 OK dan payload XML tertentu (mis. Bayar kami lebih banyak dan Anda akan mendapatkan penyimpanan yang Anda butuhkan!) Tapi saya berhenti untuk memikirkannya dan sepertinya berbusa (/ mengangkat bahu ngeri). Selain itu rasanya seperti saya memecah tanggapan kesalahan menjadi kasus yang berbeda, karena beberapa kode status http didorong dan lainnya didorong oleh konten.

Jadi apa rekomendasi industri? Praktik yang baik (tolong jelaskan alasannya!) Dan juga, dari pov klien, penanganan kesalahan seperti apa di API REST yang mempermudah kode klien?

Jadi pada awalnya saya tergoda untuk mengembalikan kesalahan aplikasi saya dengan 200 OK dan payload XML tertentu (mis. Bayar kami lebih banyak dan Anda akan mendapatkan penyimpanan yang Anda butuhkan!) Tapi saya berhenti untuk memikirkannya dan sepertinya berbusa (/ mengangkat bahu ngeri).

Saya tidak akan mengembalikan 200 kecuali benar-benar tidak ada yang salah dengan permintaan tersebut. Dari RFC2616 , 200 berarti "permintaan telah berhasil."

Jika kuota penyimpanan klien telah terlampaui (untuk alasan apa pun), saya akan mengembalikan 403 (Terlarang):

Server mengerti permintaan itu, tetapi menolak untuk memenuhinya. Otorisasi tidak akan membantu dan permintaan TIDAK HARUS diulang. Jika metode permintaan itu bukan KEPALA dan server ingin mengumumkan kepada publik mengapa permintaan itu belum dipenuhi, itu HARUS menggambarkan alasan penolakan di entitas. Jika server tidak ingin membuat informasi ini tersedia untuk klien, kode status 404 (Tidak Ditemukan) dapat digunakan sebagai gantinya.

Ini memberi tahu klien bahwa permintaan itu OK, tetapi gagal (sesuatu yang tidak dilakukan oleh 200). Ini juga memberi Anda kesempatan untuk menjelaskan masalah (dan solusinya) di badan respons.

Apa kondisi kesalahan spesifik lainnya yang ada dalam pikiran Anda?

Sumber yang bagus untuk memilih kode kesalahan HTTP yang benar untuk API Anda: http://www.codetinkerer.com/2015/12/12/choosing-an-http-status-code.html

Kutipan dari artikel:

Mulai dari mana:

2XX / 3XX:

4XX:

5XX:

Pilihan utama adalah apakah Anda ingin memperlakukan kode status HTTP sebagai bagian dari REST API Anda atau tidak.

Keduanya bekerja dengan baik. Saya setuju bahwa, sebenarnya, salah satu ide REST adalah Anda harus menggunakan kode Status HTTP sebagai bagian dari API Anda (mengembalikan 200 atau 201 untuk operasi yang sukses dan 4xx atau 5xx tergantung pada berbagai kasus kesalahan.) Namun , tidak ada polisi ISTIRAHAT. Anda dapat melakukan apa yang Anda inginkan. Saya telah melihat API non-REST jauh lebih mengerikan disebut "TENANG."

Pada titik ini (Agustus, 2015) saya merekomendasikan Anda menggunakan kode Status HTTP sebagai bagian dari API Anda. Sekarang jauh lebih mudah untuk melihat kode kembali ketika menggunakan kerangka kerja daripada sebelumnya. Secara khusus, sekarang lebih mudah untuk melihat kasus pengembalian non-200 dan badan tanggapan non-200 daripada di masa lalu.

Kode Status HTTP adalah bagian dari api Anda

1. Anda harus hati-hati memilih kode 4xx yang sesuai dengan kondisi kesalahan Anda. Anda dapat memasukkan pesan istirahat, xml, atau plaintext sebagai payload yang mencakup sub-kode dan komentar deskriptif.

2. Klien harus menggunakan kerangka kerja perangkat lunak yang memungkinkan mereka untuk mendapatkan kode status tingkat HTTP. Biasanya bisa dilakukan, tidak selalu lurus ke depan.

3. Klien harus membedakan antara kode status HTTP yang menunjukkan kesalahan komunikasi dan kode status Anda sendiri yang menunjukkan masalah tingkat aplikasi.

Kode Status HTTP BUKAN bagian dari api Anda

1. Kode status HTTP akan selalu 200 jika aplikasi Anda menerima permintaan dan kemudian merespons (baik kasus sukses maupun kesalahan)

2. SEMUA respons Anda harus menyertakan informasi "amplop" atau "header". Biasanya sesuatu seperti:

   envelope_ver: 1.0
   status: # gunakan kode yang Anda suka. Cadangan kode untuk sukses.
   msgstr "String manusia yang mencerminkan kode. Berguna untuk debugging.
   data: ... # Data respons, jika ada.

3. Metode ini dapat lebih mudah bagi klien karena status respons selalu di tempat yang sama (tidak perlu sub-kode), tidak ada batasan pada kode, tidak perlu mengambil kode status tingkat HTTP.

Berikut ini postingan dengan ide serupa: http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/

Masalah utama:

1. Pastikan untuk memasukkan nomor versi sehingga nanti Anda dapat mengubah semantik api jika diperlukan.

2. Dokumen...

Ingat ada lebih banyak kode status daripada yang didefinisikan dalam HTTP / 1.1 RFCs, registri IANA ada di http://www.iana.org/assignments/http-status-codes . Untuk kasus yang Anda sebutkan kode status 507 terdengar benar.

Seperti yang telah ditunjukkan orang lain, memiliki entitas respons dalam kode kesalahan sangat diijinkan.

Ingat bahwa kesalahan 5xx adalah sisi-server, alias klien tidak dapat mengubah apa pun pada permintaannya untuk membuat permintaan lolos. Jika kuota klien terlampaui, itu jelas bukan kesalahan server, jadi 5xx harus dihindari.

Ada dua macam kesalahan. Kesalahan aplikasi dan kesalahan HTTP. Kesalahan HTTP hanya untuk memberi tahu penangan AJAX Anda bahwa segalanya berjalan dengan baik dan tidak boleh digunakan untuk hal lain.

5xx server error

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates (RFC 2295 )
507 Insufficient Storage (WebDAV) (RFC 4918 )
509 Bandwidth Limit Exceeded (Apache bw/limited extension)
510 Not Extended (RFC 2774 )

2xx Sukses

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information (since HTTP/1.1)
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status (WebDAV)

Namun, bagaimana Anda merancang kesalahan aplikasi Anda benar-benar terserah Anda. Stack Overflow misalnya mengirimkan objek dengan response, datadan messageproperti. Respons yang saya yakini berisi trueatau falseuntuk menunjukkan apakah operasi itu berhasil (biasanya untuk operasi tulis). Data berisi muatan (biasanya untuk operasi baca) dan pesan berisi metadata tambahan atau pesan berguna (seperti pesan kesalahan saat responseada false).

Saya tahu ini sangat terlambat untuk pesta, tetapi sekarang, pada tahun 2013, kami memiliki beberapa jenis media untuk meliput penanganan kesalahan dengan cara yang umum didistribusikan (ISTIMEWA). Lihat "vnd.error", application / vnd.error + json ( https://github.com/blongden/vnd.error ) dan "Detail Masalah untuk API HTTP", aplikasi / masalah + json ( https: // alat. ietf.org/html/draft-nottingham-http-problem-05 ).

Sepakat. Filosofi dasar REST adalah menggunakan infrastruktur web. Kode Status HTTP adalah kerangka kerja pengiriman pesan yang memungkinkan para pihak untuk berkomunikasi satu sama lain tanpa menambah muatan HTTP. Mereka sudah menetapkan kode universal yang menyampaikan status respons, dan oleh karena itu, untuk benar-benar tenang, aplikasi harus menggunakan kerangka kerja ini untuk mengkomunikasikan status respons.

Mengirim respons kesalahan dalam amplop HTTP 200 menyesatkan, dan memaksa klien (api konsumen) untuk mem-parsing pesan, kemungkinan besar dengan cara non-standar, atau berpemilik. Ini juga tidak efisien - Anda akan memaksa klien Anda untuk mengurai payload HTTP setiap saat untuk memahami status respons "nyata". Ini meningkatkan pemrosesan, menambah latensi, dan menciptakan lingkungan bagi klien untuk melakukan kesalahan.

Membuat model api Anda pada 'praktik terbaik' yang ada mungkin merupakan cara yang tepat. Misalnya, berikut adalah cara Twitter menangani kode kesalahan https://developer.twitter.com/en/docs/basics/response-codes

Harap tetap menggunakan semantik protokol. Gunakan 2xx untuk respons yang berhasil dan 4xx, 5xx untuk respons kesalahan - baik itu pengecualian bisnis Anda atau lainnya. Seandainya menggunakan 2xx untuk respons apa pun adalah kasus penggunaan yang dimaksudkan dalam protokol, mereka tidak akan memiliki kode status lainnya.

Jangan lupa kesalahan 5xx juga untuk kesalahan aplikasi.

Dalam hal ini bagaimana dengan 409 (Konflik)? Ini mengasumsikan bahwa pengguna dapat memperbaiki masalah dengan menghapus sumber daya yang tersimpan.

Kalau tidak 507 (tidak sepenuhnya standar) juga dapat berfungsi. Saya tidak akan menggunakan 200 kecuali jika Anda menggunakan 200 untuk kesalahan secara umum.

Jika kuota klien terlampaui itu adalah kesalahan server, hindari 5xx dalam hal ini.