Konteks dan cakupan
Sebuah API menerima JSON dan CBOR untuk POST serta JSON Patch untuk PATCH. Klien menerima 415 setelah mengirimkan Content-Type, content encoding, atau format dokumen patch yang salah. Rancang klasifikasi server, header respons, body kesalahan, pemulihan klien, dan evolusi versi.
Ini adalah pertanyaan kontrak API backend. Media type dan format yang disebutkan adalah asumsi, bukan klaim frekuensi.
Apa yang sedang diuji oleh pewawancara
- Apakah Anda memisahkan Content-Type dan Content-Encoding permintaan dari Accept pada respons.
- Apakah Anda menggunakan 415 secara spesifik dan tidak melabeli setiap kesalahan penguraian (parsing) dengan status tersebut.
- Apakah Anda mengekspos kapabilitas PATCH dengan Accept-Patch sambil tetap menjaga kompatibilitas.
- Apakah kesalahan tersebut dapat ditindaklanjuti tanpa replay otomatis yang tidak aman.
Pertanyaan klarifikasi yang perlu diajukan
- Apakah 415 disebabkan oleh media type, content encoding, atau kapabilitas metode?
- Dapatkah klien melakukan encode ulang pada body, dan apakah ada ID permintaan yang stabil?
- Format patch dan kondisi versi sumber daya apa saja yang didukung?
- Bisakah gateway menulis ulang Content-Type, encoding, atau body kesalahan?
- Bagaimana media type baru akan diluncurkan tanpa merusak klien lama?
Jawaban 30 detik
“415 berarti metode target menolak format representasi permintaan. Server mengurai Content-Type, parameter, dan Content-Encoding, kemudian memilih parser berdasarkan kapabilitas metode dan sumber daya. Accept mendeskripsikan format respons yang diinginkan klien; header ini tidak mendeskripsikan dokumen patch yang dikirimkannya. Sumber daya PATCH dapat mengiklankan tipe dokumen yang didukung dengan Accept-Patch. Kesalahan mengembalikan kode yang stabil, nilai yang diterima dan diizinkan, serta ID permintaan. Coba lagi hanya setelah re-encoding yang aman dan analisis replay.”
Desain langkah demi langkah
1. Pisahkan semantik ketiga header
Content-Type mendeskripsikan media type dari body permintaan, Content-Encoding mendeskripsikan transfer coding, dan Accept mendeskripsikan representasi respons yang dapat diterima klien. Server tidak boleh menggunakan Accept untuk mengklasifikasikan dokumen PATCH atau menggabungkan dekompresi, kerusakan data, dan media yang tidak didukung ke dalam satu penyebab.
2. Petakan kapabilitas metode dan sumber daya
Setiap metode dan sumber daya mendeklarasikan media type serta parameter yang didukung. Misalnya, POST menerima application/json dan application/cbor, sedangkan PATCH menerima tipe dokumen JSON Patch yang terdaftar. Periksa tipe dan encoding sebelum melakukan parsing; setelah parsing, tetap jalankan validasi skema, otorisasi, dan logika bisnis.
PATCH /documents/42 HTTP/1.1
Content-Type: application/json-patch+json
Accept: application/json
Content-Length: 1283. Kembalikan respons 415 yang akurat
Kembalikan 415 dengan kode kesalahan yang stabil ketika media type atau content encoding tidak didukung. Gunakan kesalahan validasi domain untuk sintaks yang valid tetapi berisi field yang tidak valid, dan kesalahan penguraian yang jelas untuk konten yang malformed. Header respons Accept dapat mendeskripsikan representasi yang dapat dikembalikan server; header ini bukan daftar media type permintaan.
4. Iklankan kapabilitas PATCH
RFC 5789 mendefinisikan Accept-Patch; suatu sumber daya dapat mendeklarasikan media type dokumen patch yang didukung dalam OPTIONS atau respons yang berhasil. Klien kemudian dapat memilih JSON Patch atau format lain, sementara server tetap memeriksa versi sumber daya, path, dan otorisasi. Informasi yang diiklankan harus sesuai dengan set parser yang sebenarnya.
5. Buat pemulihan klien menjadi aman
Setelah menerima 415, klien membaca kode yang stabil dan tipe yang diizinkan, melakukan encode ulang pada body, atau memilih endpoint yang kompatibel. Percobaan ulang otomatis memerlukan body yang dapat dibuat ulang, tidak ada efek samping yang ireversibel, dan kunci idempotensi yang sama. Jangan mengirim ulang PATCH yang mungkin telah berhasil, dan jangan memperlakukan 415 sebagai ketidaktersediaan sementara.
6. Luncurkan dan pantau perubahan
Lakukan peluncuran canary untuk media type baru melalui gateway, server, dan SDK, sambil mempertahankan periode kompatibilitas untuk tipe lama. Segmentasikan metrik berdasarkan sumber daya, metode, tipe yang diterima, encoding, versi klien, dan alasan penolakan. Catat ID permintaan dan versi parser dalam log, jangan pernah mencatat body yang sensitif. Bandingkan header edge dan aplikasi ketika gateway menulis ulangnya.
Contoh jawaban berkualitas tinggi
“Saya memisahkan format permintaan dan respons. Server memeriksa Content-Type dan Content-Encoding berdasarkan metode dan sumber daya, hanya mengurai representasi yang didukung, lalu menjalankan validasi skema dan bisnis; Accept digunakan untuk negosiasi respons. Sumber daya PATCH mengiklankan tipe dokumen dengan Accept-Patch, tetapi setiap permintaan tetap memeriksa versi dan otorisasi. Body 415 memberikan kode yang stabil, nilai yang diterima dan diizinkan, serta ID permintaan. Klien mencoba lagi hanya setelah proses re-encoding yang aman. Tipe baru diluncurkan melalui matriks kompatibilitas dan metrik agar gateway atau SDK lama tidak mengubah semantik secara diam-diam.”
Kesalahan umum
- Menggunakan Accept untuk mengklasifikasikan body permintaan → negosiasi permintaan dan respons tercampur → periksa Content-Type dan Content-Encoding.
- Mengembalikan 415 untuk setiap kegagalan parsing → klien tidak dapat menentukan tindakan perbaikan → pisahkan kesalahan media, sintaks, dan domain.
- Mengiklankan Accept-Patch tanpa adanya parser → kontrak kapabilitas menjadi tidak benar → validasi deklarasi terhadap implementasi.
- Mencoba lagi dengan body yang sama setelah 415 → ini akan gagal atau menduplikasi efek samping → ubah encoding dan pastikan keamanan replay.
- Hanya mencatat tipe di aplikasi → perubahan akibat penulisan ulang oleh gateway menjadi tidak terlihat → bandingkan header dan ID permintaan di setiap hop.
Pertanyaan lanjutan dan jawabannya
Jika Content-Type valid tetapi Content-Encoding tidak didukung, apakah 415 tetap tepat?
RFC 9110 memasukkan content coding permintaan yang tidak dapat diterima ke dalam cakupan 415. Jelaskan masalah encoding tersebut dalam pesan kesalahan, kemudian lakukan dekompresi atau pilih encoding yang didukung sebelum memutuskan apakah body dan operasi tersebut aman untuk dicoba kembali.
Mengapa tidak hanya mengembalikan daftar tipe yang diizinkan?
Daftar sederhana mengabaikan batasan metode, parameter, dan versi. Kode yang stabil, nilai yang diterima, cakupan yang diizinkan, ID permintaan, dan tautan dokumentasi membuat tindakan perbaikan dapat dilakukan tanpa mengekspos rincian internal.
Bagaimana cara menambahkan CBOR dengan aman?
Aktifkan terlebih dahulu pada sumber daya yang tidak kritis, verifikasi fungsionalitas pass-through gateway, batasan sumber daya parser, kesetaraan skema, dan penyuntingan (redaction) log. Pertahankan mekanisme fallback ke JSON dan bandingkan 415, kegagalan parsing, serta hasil bisnis berdasarkan versi klien.