Haruskah HTTP API selalu mengembalikan benda?

Apakah ada semacam standar terkait respons API HTTP?

Setelah membaca utas wacana ini saya mulai bertanya-tanya. Kami sedang mengembangkan API HTTP JSON publik kami di tempat kerja saya, dan kami tidak mengembalikan apa pun ketika itu tidak sepenuhnya diperlukan (misalnya PUT ke / resource / {id} hanya mengembalikan 200 bila OK atau kode 4XX atau 5XX yang sesuai, tetapi tidak ada Tubuh JSON)

Haruskah kita mengembalikan generik {"success":true}seperti yang mereka bahas pada tautan di atas, atau apakah boleh mengembalikan tubuh "kosong" dan menangani semuanya dengan kode respons http?

Mengenai PUT, tetapi juga berlaku untuk POST. Bagian spesifikasi HTTP 9 sedikit kosong pada aturan atau bahkan saran (HARUS) ketika datang ke skenario yang Anda gambarkan. Baris yang relevan dengan pertanyaan Anda paling dekat dicakup oleh:

Jika sumber daya baru dibuat, server asal HARUS memberi tahu agen pengguna melalui respons 201 (Dibuat). Jika sumber daya yang ada diubah, kode respons 200 (OK) atau 204 (Tidak Ada Konten) HARUS dikirim untuk mengindikasikan keberhasilan penyelesaian permintaan.

Saya tidak berpikir saya akan kehilangan tidur di atasnya, tapi saya akan bertanya, apa yang Anda dapatkan dengan menambahkan potongan JSON ke dalam respons? Anda baru saja memilah-milah (OK, dikelompokkan mungkin berlebihan!) Respons berulang kurang akurat apa yang seharusnya kode status sudah memberi tahu Anda. Jika PUT Anda menghasilkan objek baru, pengembalian 201 (seperti niat PUT), jika ia memperbarui objek, kembali 204.

Kebetulan, API disamping, bukan 200, jika Anda tidak mengembalikan apa pun gunakan 204.

Dengan asumsi bahwa Anda sedang mengembangkan satu set antarmuka RESTful, tidak ada standar per se, jadi apa pun yang Anda lakukan, dokumentasikan dengan baik, berikan contoh dan semuanya akan baik-baik saja.

Standar HTTP dasar tidak mengamanatkan bahwa ada dokumen yang dikembalikan dengan respons. Demi ekonomi, ketika status HTTP menyampaikan semua yang diperlukan, tubuh akan boros. Namun, ada standar yang dibangun di atas HTTP yang menambahkan aturan baru.

Ada standar JSON API terbuka yang menentukan:

• Objek JSON HARUS berada di root setiap dokumen respons API JSON . (cetak miring mewakili apa yang saya tambahkan untuk memperjelas teks)

Sayangnya, standar ini tidak menentukan bagaimana cara mewakili dokumen kosong, dan ini masih dalam proses. Paling-paling saya akan menggunakannya sebagai pedoman.

Beberapa aplikasi (seperti ElasticSearch ) menyediakan api JSON lengkap, dan selalu memiliki beberapa metadata sehingga Anda dapat memiliki ide yang lebih baik tentang bagaimana server mengelola data Anda. Objek respons standar memberi tahu Anda tentang kesehatan indeks, jika permintaan menghasilkan kesalahan, berapa banyak node yang terpengaruh, dll. ElasticSearch menggunakan "application / json" untuk tipe mime sehingga tidak mungkin mereka menerapkan pedoman dalam standar jsonapi.org.

JQuery dan kerangka kerja Javascript serupa menganggap bahwa akan selalu ada dokumen. Pertanyaannya adalah berapa banyak pengecekan kesalahan yang ingin Anda paksakan pada konsumen API Anda? Jika Anda datang dengan format standar untuk semua respons yang hanya diperluas berdasarkan jenis permintaan, Anda memenuhi kebutuhan untuk dokumen pengembalian, dan dapat memfasilitasi debugging yang lebih mudah oleh konsumen API Anda.

Tidak misalnya, untuk 204 tanggapan kami tidak boleh menyertakan badan pesan. {success | status | isSuccessful: true} tidak berguna.

Dalam praktiknya (atau harus saya katakan dalam versi jquery nanti), respons kosong untuk tipe konten aplikasi / json menimbulkan kesalahan. Saya agak mengerti argumen bahwa karena itu aplikasi / json itu harus memiliki tubuh json yang valid. Jadi, respons kosong untuk tipe konten aplikasi / json adalah 'null' atau '{}' yang json valid.

Ada cara lain yang harus bekerja untuk jquery, yaitu tidak mengembalikan aplikasi / json untuk respons kosong. Cukup gunakan teks / polos atau sesuatu dan pastikan klien dapat menangani jenis itu.

Catatan saya hanya dapat mengingat 204 untuk secara eksplisit melarang isi pesan yang dikembalikan. Apa yang kami temukan adalah kami tidak selalu dapat menggunakan 204. Masalahnya adalah tajuk respons jatuh MSIE untuk 204 respons, jadi tidak ada konten dan tajuk yang buruk. Karena banyak yang menggunakan MSIE, kami harus mengubahnya ke 200 status.

Tidak, tetapi itu akan membantu konsistensi kode Anda. Ini juga bagus untuk keperluan debugging. Ini juga akan sangat membantu dalam pemeliharaan situs web. Ingat ini: Kode kesalahan adalah untuk mesin, Pesan kesalahan adalah untuk manusia. Jadi saya menyarankan agar Anda menggunakan badan tanggapan. Lagi pula, efek negatifnya hanya minimal (hanya beberapa byte yang dikirim melalui jaringan) dibandingkan dengan manfaatnya. Hal lain, itu juga akan menghindarkan Anda dari lupa menulis isi pesan saat dibutuhkan.

Saya tidak akan mengembalikan status sukses hanya dalam respon, kode kesalahan http hanya menandakan keberhasilan atau kesalahan. Saya hanya akan menyertakan menggunakan respons itu sendiri untuk menambahkan informasi kesalahan terperinci seperti kode kesalahan khusus aplikasi atau pesan kesalahan.

Untuk permintaan PUT, PATCH, dan POST, Anda biasanya mengembalikan status, mengembalikan status sumber daya setelah permintaan diterapkan, bukan respons kosong.

Untuk permintaan POST yang mewakili tindakan alih-alih hanya membuat sumber daya (tidak terlalu tenang, tetapi masih berguna dalam praktiknya), yang tidak memiliki data berguna untuk dikembalikan, saya akan mengembalikan respons yang terdiri dari objek json kosong, yaitu {}. Dengan cara itu klien mendapat respons yang valid dan menambahkan beberapa informasi di kemudian hari tidak akan mungkin merusaknya.

Untuk permintaan DELETE mengembalikan 204 dan tubuh kosong cukup umum, yang masuk akal karena sumber daya tidak ada sesudahnya.

Saya akan menyarankan kembali hanya apa yang diperlukan + sedikit klarifikasi.

Misalnya, tergantung pada bagaimana API Anda digunakan, Anda bisa menyertakan salinan objek, seperti yang ada setelah disimpan.

Jadi POST dari {key: 123} mungkin mengembalikan {key: 123, foo: 'bar'}.

Ide dasarnya adalah lebih baik mengembalikan objek daripada harus meminta lagi.

Yang mengatakan, konsumen API Anda tidak perlu objek tidak perlu mengembalikannya.

Saya biasanya mengembalikan {success: true} atau semacamnya, ketika tidak ada objek yang diperlukan pada POST PUT dan PATCH karena itu membuatnya lebih mudah untuk penerima. Yang mengatakan, lebih baik 99% dari waktu untuk mengembalikan representasi objek yang disimpan, jarang bahwa mereka tidak akan memerlukannya, dan itu "lebih murah" untuk mengirim semuanya dalam satu permintaan kemudian dalam dua.

Untuk lebih spesifik, di laboratorium itu sangat mudah untuk menangani semuanya hanya dengan kode status, di dunia nyata, jauh lebih baik untuk mengembalikan beberapa data, bahkan jika berlebihan, sehingga konsumen API dapat dengan mudah memahami apa yang ingin Anda katakan.

Mengembalikan 200 {success: true} memungkinkan orang menulis kode dengan dua cara:

if response.code == 200
  do stuff
end

dan

if response.body.success
  do stuff
end

selain itu tidak sulit untuk dilakukan di sisi Anda.

Terakhir, (maaf untuk struktur jawaban poos), dengan memberikan api JSON publik Anda menyerahkan banyak kontrol tentang bagaimana itu akan digunakan. Beberapa klien mungkin bereaksi berbeda terhadap badan yang berbeda (atau tidak ada) atau kode status.