Haruskah HTTP API selalu mengembalikan benda?


33

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?


8
{"success": true} tampaknya berlebihan. Coba gunakan kode HTTP dengan lebih baik. w3.org/Protocols/rfc2616/rfc2616-sec9.html
CodeART

HTTP 1.1 memperkenalkan KEPALA yang tidak memiliki tubuh, itu hanya respon header dari GET.
boctulus

Jawaban:


28

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.


2
Dengan POST, Anda mungkin ingin merespons dengan pengenal sumber daya yang dapat digunakan untuk memanipulasi lebih lanjut. POST /resource-> { "self" : "/resource/5" }.
Hei

1
@ Hei, saya akan menggunakan locationheader http untuk itu.
CodesInChaos

@CodesInChaos ya, itu sah-sah saja, walaupun saya belum pernah melihatnya melakukannya dalam praktiknya dan mungkin tidak akan suka itu sebagai konsumen.
Hei

1
Kasus penggunaannya adalah bahwa klien mengharapkan JSON yang valid, bahkan jika responsnya "kosong" atau tidak memiliki konten. Contoh yang baik adalah JQuery, seperti yang disebutkan oleh Abhi di bawah ini.
B Seven

12

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.


1
Ini. Ketika saya mengirim permintaan ke server API JSON, hal pertama yang saya lakukan adalah memeriksa apakah responsnya adalah JSON yang valid. Jika tidak valid, maka saya menganggap permintaan gagal meskipun saya mendapat tanggapan 200. Respons / string kosong bukan JSON yang valid.
Abhi Beckert

5

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.


3

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.


3

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.


2

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.


+1 untuk "ambil hanya apa yang dibutuhkan (dan tidak lebih)"
Niklas Rosencrantz
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.