HTTP QUERY ditujukan untuk permintaan aman yang membawa konten—misalnya kriteria pencarian kompleks—tanpa menaruh seluruh kriteria itu di URL. Metode ini dapat menjadi pilihan ketika GET tidak praktis, tetapi dukungannya tidak universal. Sebelum menggunakannya di produksi, verifikasi perilaku seluruh jalur API, dari klien hingga origin.
Spesifikasi yang relevan adalah draf HTTP safe methods with a body, yang membahas QUERY. Draf bukan jaminan bahwa browser, pustaka HTTP, proxy, gateway, cache, atau alat observabilitas sudah mendukung metode tersebut dengan benar. Karena itu, perlakukan QUERY sebagai perubahan interoperabilitas yang perlu diuji dan diluncurkan bertahap.
Kapan HTTP QUERY layak digunakan?
GET sesuai untuk pengambilan data dan memiliki semantik aman, tetapi kriterianya biasanya disampaikan melalui URI. URI yang terlalu panjang dapat ditolak oleh sebagian komponen, dan filter kompleks sulit dibaca atau dikodekan dengan konsisten. POST dapat membawa konten permintaan secara luas, tetapi bukan metode aman menurut semantik HTTP standar; komponen perantara mungkin memperlakukannya sebagai operasi yang mengubah keadaan.
QUERY dirancang sebagai metode aman yang dapat membawa konten untuk menyampaikan kriteria pemilihan sumber daya. Aman berarti klien tidak meminta perubahan keadaan pada server; ini tidak berarti permintaan bebas efek samping operasional seperti pencatatan atau pembebanan biaya. Pastikan handler QUERY hanya menjalankan operasi baca sesuai kontrak API.
- Pilih GET untuk pencarian sederhana yang muat secara wajar dalam URI dan cocok dengan kebutuhan cache serta ekosistem klien.
- Pertimbangkan QUERY jika kriteria baca kompleks perlu dikirim sebagai konten dan semua komponen di jalur mendukungnya.
- Gunakan POST jika dukungan QUERY belum memadai atau kontrak pencarian memang menggunakan POST. Dokumentasikan bahwa endpoint hanya membaca data, karena semantik metode HTTP tetap POST.
Jangan beralih ke QUERY hanya untuk menyembunyikan data sensitif. Konten permintaan tetap dapat tercatat di log aplikasi, alat tracing, atau sistem pemantauan. Gunakan HTTPS, batasi akses, dan redaksi data sensitif pada seluruh jalur.
Evaluasi kompatibilitas di seluruh jalur
Susun inventaris komponen yang menerima, meneruskan, atau mencatat permintaan: klien, pustaka HTTP, load balancer, WAF, reverse proxy, API gateway, server aplikasi, cache, dan sistem observabilitas. Uji konfigurasi serta versi yang benar-benar dipakai; dukungan di satu komponen tidak membuktikan bahwa seluruh rantai mendukung QUERY.
Klien dan server
Pastikan klien dapat mengirim metode QUERY beserta konten, header yang diperlukan, dan autentikasi. Periksa juga batasan API klien, kebijakan CORS untuk aplikasi browser, serta kemungkinan permintaan preflight. Di sisi server, pastikan router mengenali QUERY, validasi konten berjalan, dan metode tidak jatuh ke handler yang keliru. Tetapkan tipe konten dan skema permintaan secara eksplisit.
Proxy, gateway, dan cache
Komponen perantara dapat menolak metode yang tidak dikenal, mengubah perilaku penerusan, atau menerapkan kebijakan yang hanya mencakup metode umum. Uji jalur penuh, termasuk aturan WAF, autentikasi, pembatasan laju, timeout, dan penanganan kesalahan. Jangan menganggap keberhasilan permintaan langsung ke origin sebagai bukti kompatibilitas produksi.
Cache HTTP umumnya mengandalkan metode dan URI sebagai bagian dari kunci cache; konten permintaan tidak otomatis menjadi bagian dari kunci tersebut. Jangan mengaktifkan cache untuk QUERY kecuali cache yang digunakan secara eksplisit mendukung semantik dan kunci yang benar. Jika dukungan itu tidak dapat diverifikasi, nonaktifkan cache untuk endpoint QUERY dan gunakan kebijakan penyimpanan yang sesuai.
Observabilitas dan keamanan
Pastikan log, tracing, metrik, dan dashboard mengenali QUERY sebagai metode tersendiri. Catat jumlah permintaan, latensi, status respons, dan jalur versi endpoint tanpa menyimpan konten sensitif. Periksa apakah alat observabilitas membuang atau mencatat body secara default; terapkan redaksi sebelum rollout. Validasi ukuran konten, skema, autentikasi, dan otorisasi seperti pada endpoint lain.
Rollout bertahap dengan feature flag
- Siapkan endpoint dan kontrak. Pertahankan endpoint lama. Tambahkan QUERY dengan hasil, validasi, batasan, dan kebijakan keamanan yang setara. Hindari mengubah bentuk respons tanpa kebutuhan.
- Uji di lingkungan terkontrol. Jalankan permintaan melalui jalur jaringan yang sama dengan produksi, termasuk gateway dan WAF. Uji klien yang didukung, konten tidak valid, autentikasi, timeout, serta respons kesalahan.
- Aktifkan di balik feature flag. Mulai dengan pengguna internal atau lalu lintas canary yang kecil. Flag harus dapat mematikan QUERY dan mengarahkan klien kembali ke endpoint lama tanpa menunggu deployment baru.
- Bandingkan hasil dan metrik. Pantau volume, tingkat sukses, respons 4xx dan 5xx, latensi, timeout, serta kegagalan per komponen dan per jenis klien. Bandingkan hasil pencarian QUERY dengan endpoint lama pada sampel yang aman, tanpa menggandakan operasi yang memiliki efek samping.
- Perluas secara bertahap. Naikkan porsi lalu lintas hanya jika metrik stabil, hasil sesuai, dan tidak ada pola kegagalan pada komponen perantara. Pertahankan endpoint lama selama periode adopsi yang ditentukan.
Tentukan ambang keberhasilan dan penghentian sebelum canary, berdasarkan SLO dan baseline layanan—jangan menetapkan angka universal. Hentikan perluasan jika tingkat kesalahan atau latensi melewati ambang, hasil berbeda, ada klien penting yang gagal, atau log menunjukkan penolakan metode maupun kehilangan konten.
Pengujian dan rollback
Uji alur end-to-end dengan klien produksi yang sebenarnya, bukan hanya alat yang langsung mengirim permintaan ke server. Sertakan pengujian untuk metode QUERY dengan body melalui setiap proxy dan gateway; respons terhadap metode yang tidak didukung; body kosong atau tidak valid; batas ukuran; autentikasi; CORS jika relevan; serta perilaku cache dan logging. Uji pula fallback klien agar kegagalan QUERY tidak membuat permintaan hilang atau menghasilkan hasil yang keliru.
Rollback berarti menonaktifkan flag, mengarahkan lalu lintas ke endpoint lama, dan memverifikasi bahwa klien serta metrik kembali normal. Jangan menghapus endpoint lama sebelum adopsi QUERY terbukti dan rencana pemulihan tidak lagi bergantung padanya. Jika masalah berasal dari cache, gateway, atau pencatatan, nonaktifkan fitur pada komponen terkait; mengubah handler aplikasi saja mungkin tidak cukup.
Keputusan praktis: gunakan QUERY hanya jika kebutuhan konten permintaan lebih kuat daripada biaya kompatibilitas, dan pengujian membuktikan dukungan pada jalur produksi. Jika tidak, GET dengan parameter yang sesuai atau POST dengan kontrak baca yang terdokumentasi lebih mudah dioperasikan.
Komentar
0 komentar
Masuk ke akun kamu untuk ikut berkomentar.
Belum ada komentar
Jadilah yang pertama ikut berdiskusi!