HTTP QUERY: Kaedah Request Baharu Antara GET dan POST

Selama ini, developer yang mempunyai query kompleks tetapi mahukan operasi read-only biasanya terpaksa memilih antara dua pilihan. Gunakan GET dan masukkan semua parameter ke dalam URL, atau gunakan POST walaupun request tersebut sebenarnya tidak mengubah apa-apa data.

Kedua-duanya ada masalah.

URL yang terlalu panjang boleh menyusahkan sesetengah perantara dan parameter di dalam URL juga mudah masuk ke dalam log. POST pula tidak mempunyai semantik safe dan idempotent seperti GET, jadi infrastruktur HTTP tidak boleh menganggapnya sebagai operasi bacaan yang selamat untuk diulang atau di-cache.

Pada Jun 2026, IETF menerbitkan RFC 10008, yang memperkenalkan kaedah HTTP baharu bernama QUERY. Ia direka untuk menjadi safe dan idempotent seperti GET, tetapi juga boleh membawa body seperti POST.

Spesifikasi ini ialah hasil daripada kerja draft-ietf-httpbis-safe-method-w-body oleh Julian Reschke, James Snell (Cloudflare), dan Mike Bishop (Akamai). Kaedah tersebut kini turut disenaraikan dalam IANA HTTP Method Registry sebagai kaedah yang safe dan idempotent.

Artikel ini melihat kenapa QUERY diperlukan, bagaimana ia berfungsi pada peringkat HTTP, dan sejauh mana sokongannya pada pertengahan 2026.

Masalahnya: Dua kaedah, kedua-duanya ada kekangan

GET bersifat safe dan idempotent. Cache, proksi dan pelbagai komponen HTTP memang direka untuk mengendalikan GET.

Masalahnya ialah query perlu diletakkan di dalam URI.

Itu boleh menjadi masalah apabila query semakin kompleks:

• Had panjang URL bergantung pada perisian dan perantara yang digunakan. HTTP mengesyorkan sokongan sekurang-kurangnya 8000 oktet, tetapi pelaksanaan sebenar boleh berbeza.
• Setiap kombinasi parameter menghasilkan URI yang berbeza. Ini boleh menyebabkan jumlah variasi cache dan data analitik meningkat.
• Kandungan URI lebih mudah muncul dalam access log, sejarah pelayar dan sistem pemantauan. Jika query mengandungi maklumat sensitif, semuanya direkodkan secara lalai.

POST menyelesaikan masalah body kerana query boleh dihantar sebagai kandungan request.

Tetapi POST bukan kaedah safe dan bukan idempotent. Infrastruktur tidak boleh menganggap request tersebut sebagai operasi bacaan yang selamat untuk diulang. Cache juga tidak mengendalikan POST dengan cara yang sama seperti GET.

Sebab itulah banyak API akhirnya menggunakan corak POST untuk operasi carian.

QUERY cuba mengisi ruang antara kedua-duanya.

Apa sebenarnya QUERY?

Menurut spesifikasi, QUERY meminta server memproses kandungan request secara safe dan idempotent, kemudian mengembalikan hasil pemprosesan tersebut.

Kandungan request bersama Content-Type menentukan query yang dihantar. Server pula menentukan skop query berdasarkan request target.

Perbezaan penting berbanding GET ialah body QUERY boleh mengandungi query tersebut. Responsnya pula merupakan hasil pemprosesan query, bukannya semata-mata representasi resource yang ditunjukkan oleh URI.

Antara sifat utama QUERY ialah:

Disebabkan QUERY bersifat safe dan idempotent, klien boleh mengulang request selepas kegagalan sambungan. Cache juga boleh menyimpan responsnya apabila syarat cache dipenuhi.

Ini memberikan QUERY semantik yang lebih sesuai untuk operasi carian berbanding menggunakan POST semata-mata kerana query tersebut mempunyai body.

Server mesti menolak request QUERY jika Content-Type tiada atau tidak konsisten dengan kandungan body.

Query yang berjaya tetapi tidak menghasilkan kandungan boleh menggunakan 204 No Content. Jika hasil tersedia dalam respons, 200 OK boleh digunakan.

Rupa QUERY pada peringkat rangkaian

Contoh daripada RFC boleh dilihat seperti ini:

QUERY /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded

q=foo&limit=10&sort=-published

Perbezaannya mudah dilihat.

Dengan GET, query biasanya berada dalam URI:

GET /feed?q=foo&limit=10&sort=-published HTTP/1.1

Dengan QUERY, /feed kekal sebagai request target, manakala query sebenar berada di dalam body.

Spesifikasi tidak menghadkan penggunaan kepada satu format sahaja. Query boleh menggunakan mana-mana media type yang mempunyai semantik query, termasuk application/json, GraphQL, SQL, JSONPath atau bahasa query RDF.

Content-Type memberitahu server format yang digunakan dan server menentukan sama ada ia menyokong format tersebut.

Laluan keluar: Location dan Content-Location

RFC 10008 turut menyediakan Location dan Content-Location untuk menghubungkan hasil QUERY dengan resource HTTP yang boleh diakses semula.

• Location boleh mengenal pasti equivalent resource untuk query tersebut. URI itu kemudiannya boleh digunakan dengan GET untuk mengakses query yang sama tanpa perlu menghantar body sekali lagi.
• Content-Location boleh mengenal pasti URI bagi hasil query tertentu. Ini membolehkan hasil tersebut diambil semula atau dikongsi melalui URI.

Bahagian ini penting untuk aplikasi yang mempunyai query berat atau mengambil masa untuk diproses.

Sebagai contoh, server boleh menerima QUERY, menjalankan pemprosesan yang mahal, kemudian menyediakan URI yang boleh digunakan untuk mengambil hasil tersebut melalui GET.

Corak seperti ini boleh berguna untuk polling, pagination dan penggunaan cache.

Accept-Query: Mengiklankan bahasa yang anda fahami

Spesifikasi ini juga mendaftarkan header Accept-Query.

Server boleh menggunakannya untuk memberitahu klien bahawa resource tersebut menyokong QUERY serta format query yang diterimanya:

HTTP/1.1 200 OK
Accept-Query: application/sql, application/jsonpath

Nilai tersebut ialah Structured Fields List. Header ini juga boleh diberikan pada respons GET, membolehkan klien mengetahui sokongan server sebelum menghantar request QUERY.

Tools seperti h3 turut menyediakan helper seperti appendAcceptQuery dan requireContentType untuk membantu proses tersebut.

Nota keselamatan yang perlu diingat

• Privasi tidak semestinya bermaksud query menjadi rahsia. Kandungan URI lebih lazim direkodkan oleh log dan perantara berbanding body request. Menggunakan body untuk query boleh mengurangkan pendedahan tersebut. Namun, server masih perlu berhati-hati apabila menghasilkan URI melalui Location atau Content-Location. URI itu tidak sepatutnya mengandungi data sensitif daripada query asal.
• Cache perlu mengira key dengan betul. Jika cache menggunakan request body sebagai sebahagian daripada cache key, ia perlu menggunakan kandungan yang sama seperti yang digunakan oleh server. Jika tidak, respons untuk satu query berpotensi diberikan kepada query yang lain.
• Preflight CORS diperlukan. QUERY bukan kaedah yang termasuk dalam CORS safelisted methods. Request QUERY lintas sumber daripada pelayar akan menyebabkan preflight OPTIONS. Server perlu memasukkan QUERY dalam Access-Control-Allow-Methods.
• Body masih mempunyai risiko saiz. Oleh kerana body QUERY boleh mengandungi input yang besar dan dikawal pengguna, server perlu menetapkan had saiz serta melakukan validasi seperti yang dilakukan untuk request POST.

Sokongan sebenar pada hari ini (Ogos 2026)

Sokongan untuk QUERY memang sudah wujud, tetapi belum seragam. Bahagian server jauh lebih bersedia berbanding pelayar.

Di bahagian server (Server-side), boleh digunakan sekarang:

• Node.js — QUERY berfungsi secara terus sejak versi 22.2.0 melalui parser llhttp, dan node:http mendedahkannya sebagai kaedah HTTP. Node 24 turut mengendalikannya. Klien fetch undici menambah sokongan QUERY dalam versi 8.6.0.
• Go — net/http boleh mengendalikan QUERY seperti kaedah tersuai lain melalui http.NewRequest. Tiada perubahan khas diperlukan pada standard library.
• h3 (unjs) — Menyediakan sokongan app.query() serta helper untuk Accept-Query dan Content-Type.
• ASP.NET Core — Route boleh menggunakan MapMethods("/search", ["QUERY"], handler). .NET 10 juga mula menyediakan HttpMethod.Query di bahagian klien.
• Eclipse Jetty dan Apache Tomcat — Sokongan sedang dilaksanakan. Protokol W3C Linked Web Storage juga telah mula menggunakannya untuk operasi carian.
• Express 5 — Menyediakan helper routing app.query(). express.json() masih diperlukan jika body JSON hendak dibaca melalui req.body.
• Fastify — Boleh menerima route QUERY secara terus tanpa tetapan tambahan.

Di bahagian klien (Client-side):

• fetch(url, { method: "QUERY", body }) boleh digunakan kerana Fetch tidak menyekat kaedah tersebut. Ia hanya melarang CONNECT, TRACE dan TRACK. Pastikan kaedah ditulis sebagai QUERY dalam huruf besar.
• Pelayar belum menyokong QUERY secara native. HTML <form> juga belum mempunyai mekanisme deklaratif untuk menghantar body menggunakan QUERY dan akan menggunakan kaedah yang disokongnya seperti GET atau POST.
• Pelayar belum meng-cache respons QUERY secara native walaupun spesifikasi HTTP membenarkan respons tersebut di-cache.

Masih tiada sokongan:

• Tidak semua framework sudah bersedia. Action Pack dalam Rails masih menolak QUERY dengan status 405 (UnknownHttpMethod). Django, Spring dan Laravel juga memerlukan sokongan tambahan bergantung pada lapisan routing yang digunakan.
• API gateway, WAF, CDN dan proksi korporat mungkin belum mengenali kaedah ini. Ini penting kerana request HTTP jarang bergerak terus daripada klien ke server. Ia mungkin melalui beberapa lapisan perantara yang mempunyai senarai kaedah HTTP tersendiri.

Patutkah anda menggunakannya sekarang?

Jawapan ringkasnya: jika anda mengawal kedua-dua hujung, boleh pertimbangkan.

Untuk API dalaman, komunikasi antara servis atau sistem yang mempunyai klien dan server sendiri, QUERY boleh menjadi pilihan yang menarik. Ia paling berguna apabila operasi tersebut memang bersifat bacaan tetapi query terlalu besar atau kompleks untuk diletakkan dalam URI.

Contohnya:

• carian dengan banyak penapis;
• query berstruktur;
• operasi geospatial;
• query ala-GraphQL;
• sistem dalaman yang memerlukan body untuk operasi bacaan.

Untuk API awam, keadaan masih berbeza.

Lebih selamat untuk menyediakan fallback seperti POST atau GET bergantung pada keperluan API anda. Jika server atau perantara mengembalikan 405 atau 501, klien boleh menggunakan kaedah alternatif yang disediakan.

PATCH sendiri mengambil masa yang lama untuk mendapat sokongan menyeluruh selepas diperkenalkan melalui RFC 5789 pada 2010. QUERY mungkin melalui proses yang sama: sokongan muncul dahulu di server, kemudian framework, kemudian infrastruktur seperti CDN dan proksi, dan akhirnya pelayar serta HTML.

Spesifikasi QUERY sendiri menyediakan mekanisme seperti Location dan Content-Location yang boleh membantu dalam proses peralihan kepada URI yang boleh diakses melalui GET.

Jadi, tidak perlu menukar semua API kepada QUERY sekarang. Untuk projek baharu yang mengawal keseluruhan stack, ia boleh diuji. Untuk API awam yang bergantung pada banyak lapisan pihak ketiga, tunggu sehingga sokongannya lebih meluas.

Kenapa QUERY dan bukan SEARCH?

HTTP Method Registry sebenarnya sudah mempunyai beberapa kaedah safe dan idempotent yang boleh membawa body, termasuk PROPFIND, REPORT dan SEARCH daripada dunia WebDAV.

Draf awal spesifikasi ini juga menggunakan nama SEARCH.

Akhirnya, QUERY dipilih kerana nama tersebut lebih jelas menggambarkan tujuan kaedah itu. Ia berkait terus dengan konsep query dalam HTTP dan tidak terlalu bergantung kepada sejarah WebDAV.

---

Ringkasnya: QUERY mengisi ruang yang selama ini agak janggal dalam HTTP: operasi bacaan yang memerlukan body. GET masih pilihan terbaik untuk kebanyakan permintaan biasa, manakala POST masih berguna apabila operasi tidak bersifat safe atau apabila infrastruktur belum menyokong QUERY.

Untuk aplikasi yang mempunyai query kompleks dan mengawal kedua-dua klien serta server, QUERY menawarkan semantik yang lebih tepat. Untuk API awam, masih terlalu awal untuk bergantung kepadanya sepenuhnya.

Standardnya sudah ada. Sekarang tinggal menunggu infrastruktur web mengejarnya.