Wawancara Backend: Kapan API Harus Mengembalikan 204 No Content?

Petunjuk dan ruang lingkup

Rancang kontrak respons kosong (empty-response) untuk REST API. Bagaimana seharusnya respons penghapusan yang berhasil? Haruskah kueri koleksi tanpa hasil yang cocok mengembalikan 204? Apa yang harus dikembalikan oleh pembaruan yang berhasil ketika tidak ada representasi yang diperlukan? Pisahkan antara sumber daya yang hilang, operasi yang berhasil tanpa representasi, operasi asinkron, dan koleksi kosong yang valid. Asumsikan klien dibuat secara otomatis (generated clients) dalam beberapa bahasa dan kontrak berjangka panjang.

Apa yang sedang diuji oleh pewawancara

Perlakukan kode status sebagai semantik sumber daya, bukan jalan pintas untuk "tidak ada data". 204 berarti sukses tanpa konten pesan dan tidak boleh membawa body pesan; 200 dapat mengembalikan representasi yang stabil seperti []; 404 berarti sumber daya target tidak ada atau tidak memiliki representasi saat ini. Diskusikan idempotensi DELETE, cache, decoding SDK, dan dokumentasi OpenAPI.

Klarifikasi sebelum menjawab

1. Apa targetnya? Menghapus satu sumber daya, memperbarui satu sumber daya, dan mengueri koleksi memiliki semantik yang berbeda.
2. Apakah koleksi kosong merupakan hasil yang normal? Jika ya, 200 dengan [] biasanya mempertahankan tipe respons yang stabil lebih baik daripada 204.
3. Haruskah klien mendekode satu bentuk JSON? Klien yang dibuat secara otomatis yang selalu membaca body dapat mengubah 204 menjadi EOF yang tidak terduga kecuali jika ia memiliki percabangan eksplisit.
4. Apakah keberhasilan memerlukan representasi baru, ETag, atau ID tugas asinkron? Jika demikian, pertahankan body respons dan pilih 200, 201, atau 202.

Keputusan yang direkomendasikan dan derivasi

Definisikan kontrak berdasarkan operasi dan kebutuhan representasi:

• DELETE /users/42 yang berhasil tanpa representasi untuk dikembalikan dapat menggunakan 204. Jika penghapusan berulang didefinisikan sebagai keberhasilan yang idempoten, responsnya juga dapat tetap 204, tetapi dokumentasikan hal tersebut.
• Jika GET /users?team=none menemukan koleksi yang ada tanpa anggota, kembalikan 200 dan [] untuk mempertahankan tipe daftar; baris berjumlah nol bukanlah sumber daya yang hilang.
• Jika GET /users/42 tidak dapat menemukan target, kembalikan 404. Itu adalah semantik target sumber daya, bukan semantik daftar kosong.
• Jika PUT /users/42 berhasil dan klien memerlukan representasi baru, kembalikan 200 dengan JSON. Jika tidak ada representasi yang diperlukan, 204 valid dan ETag masih dapat membawa metadata.
• Jika permintaan diterima tetapi pekerjaan masih berlanjut, kembalikan 202 dengan tautan status tugas alih-alih menyamarkannya 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 mendefinisikan 204 sebagai tidak memiliki konten pesan, sehingga klien, proksi, dan pengujian harus memperlakukan ketiadaan body sebagai bagian dari kontrak. Jangan menaruh kesalahan bisnis (business errors) di dalam 200 yang berhasil hanya demi keseragaman, dan jangan mengubah setiap hasil kosong menjadi 204 hanya untuk menghemat beberapa bita.

Alternatif dan pertukaran (trade-offs)

200 dengan array kosong menjaga tipe tetap stabil, mudah untuk SDK yang dibuat otomatis, dan dapat membawa metadata paginasi; biayanya hanya beberapa bita. 204 secara jelas mengekspresikan keberhasilan tanpa representasi, cocok untuk DELETE atau pembaruan yang tidak mengulang (echo) data; klien harus menangani body yang tidak ada dan tidak dapat membaca detail kesalahan di sana. Cadangkan 404 untuk sumber daya target yang hilang, bukan untuk koleksi kosong yang valid.

Mode kegagalan, batasan, dan contoh kasus buruk

• Mengembalikan 204 untuk daftar GET yang kosong membuat klien memperlakukan hasil kosong yang valid sebagai tipe respons yang berbeda, sehingga merusak paginasi dan decoding generik.
• Mengirim body JSON dengan 204 melanggar semantik pesannya; proksi dapat membuangnya dan perilaku klien akan berbeda-beda.
• Mengembalikan 204 pada DELETE pertama dan 404 pada percobaan ulang (retry) tanpa mendokumentasikan idempotensi akan menimbulkan kesalahan percobaan ulang yang seharusnya dapat dihindari.
• Mengembalikan 200 dengan { "error": ... } membuat sistem pemantauan dan SDK mengklasifikasikan kegagalan bisnis sebagai keberhasilan.
• Mengembalikan 204 setelah pembaruan yang memerlukan ETag baru tetapi menghilangkan header respons akan mencegah caching yang aman atau kontrol konkurensi.

Daftar periksa pengujian dan verifikasi

Tulis uji kontrak untuk status, body, Content-Type, ETag, dan header cache pada setiap endpoint. Cakup DELETE pertama dan berulang, koleksi kosong, sumber daya tunggal yang hilang, pembaruan dengan dan tanpa representasi, percabangan asinkron 202, penerusan proksi, dan decoding SDK. Buat setidaknya satu klien dari OpenAPI dan verifikasi bahwa 204 tidak memicu kesalahan penguraian JSON; periksa bahwa pemantauan memisahkan 2xx, 404, dan kesalahan bisnis terstruktur.

Pertanyaan lanjutan

Bisakah 204 membawa ETag atau header respons lainnya?

Ya. Melarang konten pesan tidak berarti melarang metadata. ETag, kontrol cache, atau trace ID dapat mendukung kontrol konkurensi dan diagnosis, tetapi dokumentasikan kapan header tersebut ada.

Haruskah halaman kosong berupa 200 atau 204?

Jika representasinya berupa daftar, lebih disukai 200 dengan array kosong dan metadata paginasi. Pertimbangkan 204 hanya jika "berhasil tanpa representasi" dinyatakan secara eksplisit dan setiap klien mampu menangani body yang tidak ada.

Haruskah DELETE mengembalikan 404 ketika sumber daya tidak ada?

Tidak selalu. Jika penghapusan berarti "memastikan sumber daya tidak ada", permintaan berulang dapat mengembalikan 204. Jika pemanggil perlu mengetahui apakah sumber daya tersebut sebelumnya ada, kembalikan 404. Catat pilihan tersebut secara konsisten dalam dokumentasi, SDK, dan pemantauan.