Temu Duga Backend: Bilakah API Patut Mengembalikan 204 No Content?

Gesaan dan skop

Reka bentuk kontrak respons kosong untuk REST API. Bagaimanakah pemadaman yang berjaya patut memberi respons? Patutkah pertanyaan koleksi tanpa sebarang padanan mengembalikan 204? Apakah yang patut dikembalikan oleh kemas kini yang berjaya apabila tiada perwakilan diperlukan? Asingkan sumber yang hilang, operasi yang berjaya tanpa perwakilan, operasi tak segerak (asynchronous), dan koleksi kosong yang sah. Andaikan klien dijana dalam beberapa bahasa dan kontrak yang bertahan lama.

Perkara yang diuji oleh penemu duga

Anggap kod status sebagai semantik sumber, bukan jalan pintas untuk "tiada data." 204 bermaksud kejayaan tanpa kandungan mesej dan tidak boleh membawa jasad mesej; 200 boleh mengembalikan perwakilan yang stabil seperti []; 404 bermaksud sumber sasaran tiada atau tidak mempunyai perwakilan semasa. Bincangkan keidempotennan DELETE, cache, penyahkodan SDK, dan dokumentasi OpenAPI.

Penjelasan sebelum menjawab

1. Apakah sasarannya? Memadam satu sumber, mengemas kini satu sumber, dan menanyakan koleksi mempunyai semantik yang berbeza.
2. Adakah koleksi kosong merupakan hasil yang normal? Jika ya, 200 dengan [] biasanya mengekalkan jenis respons yang stabil dengan lebih baik daripada 204.
3. Adakah klien mesti menyahkod satu bentuk JSON? Klien yang dijana yang sentiasa membaca jasad mungkin menjadikan 204 sebagai EOF yang tidak dijangka melainkan ia mempunyai cawangan yang jelas.
4. Adakah kejayaan memerlukan perwakilan baharu, ETag, atau ID tugas tak segerak? Jika ya, kekalkan jasad respons dan pilih 200, 201, atau 202.

Keputusan dan penerbitan yang disyorkan

Takrifkan kontrak mengikut operasi dan keperluan perwakilan:

• DELETE /users/42 yang berjaya tanpa perwakilan untuk dikembalikan boleh menggunakan 204. Jika pemadaman berulang ditakrifkan sebagai kejayaan yang idempoten, ia juga boleh kekal sebagai 204, tetapi dokumenkannya.
• Jika GET /users?team=none menemui koleksi sedia ada tanpa sebarang ahli, kembalikan 200 dan [] untuk mengekalkan jenis senarai; sifar baris bukanlah sumber yang hilang.
• Jika GET /users/42 tidak dapat mencari sasaran, kembalikan 404. Itu adalah semantik sumber sasaran, bukan semantik senarai kosong.
• Jika PUT /users/42 berjaya dan klien memerlukan perwakilan baharu, kembalikan 200 dengan JSON. Jika tiada perwakilan diperlukan, 204 adalah sah dan ETag masih boleh membawa metadata.
• Jika permintaan diterima tetapi kerja diteruskan, kembalikan 202 dengan pautan status tugas dan bukannya menyamar sebagai 204.

HTTP/1.1 204 No Content
ETag: "user-42-v7"
Cache-Control: no-store

HTTP/1.1 200 OK
Content-Type: application/json

[]

RFC 9110 mentakrifkan 204 sebagai tidak mempunyai kandungan mesej, jadi klien, proksi, dan ujian harus menganggap ketiadaan jasad sebagai sebahagian daripada kontrak. Jangan meletakkan ralat perniagaan di dalam 200 yang berjaya semata-mata untuk keseragaman, dan jangan menukar setiap hasil kosong kepada 204 untuk menjimatkan beberapa bait.

Alternatif dan pertukaran (trade-offs)

Tatasusunan kosong 200 memastikan jenis kekal stabil, mudah untuk SDK yang dijana, dan boleh membawa metadata penomboran halaman (pagination); ia hanya melibatkan kos beberapa bait. 204 menyatakan kejayaan secara jelas tanpa perwakilan, sesuai untuk DELETE atau kemas kini yang tidak memantulkan data; klien mesti mengendalikan ketiadaan jasad dan tidak boleh membaca butiran ralat di situ. Simpan 404 untuk sumber sasaran yang hilang dan bukannya koleksi kosong yang sah.

Mod kegagalan, sempadan, dan contoh lawan

• Mengembalikan 204 untuk senarai GET yang kosong menyebabkan klien menganggap hasil kosong yang sah sebagai jenis respons yang berbeza, merosakkan penomboran halaman dan penyahkodan generik.
• Menghantar jasad JSON dengan 204 melanggar semantik mesejnya; proksi mungkin membuangnya dan tingkah laku klien akan menyimpang.
• Mengembalikan 204 pada DELETE pertama dan 404 pada percubaan semula tanpa mendokumentasikan keidempotennan menghasilkan ralat percubaan semula yang boleh dielakkan.
• Mengembalikan 200 dengan { "error": ... } menyebabkan pemantauan dan SDK mengklasifikasikan kegagalan perniagaan sebagai kejayaan.
• Mengembalikan 204 selepas kemas kini yang memerlukan ETag baharu tetapi meninggalkan pengepala respons menghalang caching yang selamat atau kawalan konkurensi.

Senarai semak ujian dan pengesahan

Tulis ujian kontrak untuk status, jasad, Content-Type, ETag, dan pengepala cache pada setiap titik akhir. Rangkumi DELETE kali pertama dan berulang, koleksi kosong, sumber tunggal yang hilang, kemas kini dengan dan tanpa perwakilan, cawangan tak segerak 202, pemajuan proksi, dan penyahkodan SDK. Jana sekurang-kurangnya satu klien daripada OpenAPI dan sahkan bahawa 204 tidak mencetuskan ralat penghuraian JSON; semak bahawa pemantauan mengasingkan 2xx, 404, dan ralat perniagaan berstruktur.

Soalan susulan

Bolehkah 204 membawa ETag atau pengepala respons lain?

Ya. Melarang kandungan mesej tidak melarang metadata. ETag, kawalan cache, atau trace ID boleh menyokong kawalan konkurensi dan diagnosis, tetapi dokumenkan bila ia hadir.

Patutkah halaman kosong menjadi 200 atau 204?

Jika perwakilan ialah senarai, utamakan 200 dengan tatasusunan kosong dan metadata penomboran halaman. Pertimbangkan 204 hanya apabila "kejayaan tanpa perwakilan" dinyatakan secara eksplisit dan setiap klien mengendalikan ketiadaan jasad.

Adakah DELETE mesti mengembalikan 404 apabila sumber tiada?

Tidak semestinya. Jika pemadaman bermaksud "memastikan sumber tiada," permintaan berulang boleh mengembalikan 204. Jika pemanggil perlu mengetahui sama ada ia wujud sebelum ini, kembalikan 404. Rekod pilihan tersebut secara konsisten dalam dokumentasi, SDK, dan pemantauan.