Metode HTTP QUERY Dijelaskan: RFC 10008, QUERY vs GET vs POST

Metode HTTP QUERY adalah metode permintaan baru, yang didefinisikan dalam RFC 10008 (Juni 2026), yang mengirim kueri di dalam body permintaan dan bersifat aman sekaligus idempoten. Anggap saja sebagai GET dengan body: Anda mendapatkan keluasan POST untuk filter yang kompleks dan jaminan GET untuk caching serta percobaan ulang otomatis.

Jika Anda pernah menjejalkan filter berukuran 3 KB ke dalam URL, atau mengirim pencarian hanya-baca sebagai POST lalu melihat cache dan logika percobaan ulang Anda mengabaikannya, QUERY adalah solusinya. Panduan ini membahas apa yang dikatakan spesifikasi, bagaimana QUERY dibandingkan dengan GET dan POST, apa yang mendukungnya saat ini, dan cara menguji endpoint QUERY dengan coding agent Anda.

Apa itu metode HTTP QUERY?

QUERY adalah metode HTTP yang meminta resource target menjalankan kueri yang dijelaskan dalam konten permintaan dan mengembalikan hasilnya. Body permintaan dan Content-Type-nya menentukan kueri tersebut. Metode ini aman (klien tidak mengharapkan perubahan status) dan idempoten (mengulanginya memberikan efek yang sama), sehingga klien, proxy, dan cache dapat mencoba ulang dan menyimpannya di cache seperti GET.

Spesifikasinya adalah RFC 10008, “The HTTP QUERY Method”, sebuah Proposed Standard yang diterbitkan pada Juni 2026 oleh Julian Reschke (greenbytes), James M. Snell (Cloudflare), dan Mike Bishop (Akamai). IANA telah menambahkannya ke HTTP Method Registry dengan “safe: yes, idempotent: yes”, tepat di samping metode SEARCH era WebDAV yang nyaris menjadi bentuk akhirnya.

Permintaan QUERY terlihat seperti ini:

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

select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

Server menjawab dengan 200 OK dan hasilnya ada di dalam body.

Mengapa GET dan POST tidak cukup

Sebelum ada QUERY, Anda punya dua opsi untuk pembacaan kompleks, dan keduanya bocor.

GET menaruh semuanya di URL. RFC 10008 mencantumkan empat masalah dengan hal itu:

1. Batas ukuran tidak diketahui sebelumnya, karena sebuah permintaan melewati banyak sistem. RFC 9110 hanya merekomendasikan agar pengirim dan penerima mendukung setidaknya 8.000 oktet.
2. Mengodekan data terstruktur ke dalam URI yang valid itu boros.
3. URI jauh lebih sering dicatat dalam log dan di-bookmark dibandingkan body permintaan, yang menjadi masalah privasi untuk filter yang sensitif.
4. Setiap kombinasi input kueri menjadi resource-nya sendiri.

GET dengan body juga bukan jawabannya. RFC 9110 menyatakan konten dalam permintaan GET tidak memiliki semantik yang terdefinisi. Sebagian server membacanya, sebagian mengabaikannya, dan sebagian proxy menolak permintaan tersebut. Anda tidak bisa mengandalkannya di sepanjang jalur.

POST berfungsi, tetapi ia berbohong soal niatnya. Pencarian POST berjalan dengan baik, namun tidak ada yang memberi tahu klien, cache, proxy, atau pustaka percobaan ulang bahwa operasi tersebut hanya-baca. Jadi cache melewatinya dan klien tidak akan mencobanya ulang setelah koneksi terputus. Jika Anda pernah harus memasang idempotency key pada operasi baca murni hanya agar percobaan ulang aman, Anda sudah merasakannya.

QUERY mempertahankan body milik POST dan menambahkan jaminan milik GET.

QUERY vs GET vs POST

Berikut perbandingannya, berdasarkan Tabel 1 dari RFC 10008:

Versi singkatnya: gunakan GET saat kueri muat dengan nyaman di URL, QUERY saat tidak muat, dan POST hanya saat permintaan mengubah status. Untuk menyegarkan kembali pengetahuan tentang metode klasik, lihat panduan kami tentang metode HTTP dan GET vs POST.

Apa yang didefinisikan RFC 10008

Content-Type bersifat wajib

Server HARUS menggagalkan QUERY yang Content-Type-nya hilang atau tidak konsisten dengan body-nya. RFC merekomendasikan kode status berikut:

• 400 Bad Request: tidak ada media type, atau tipe yang tidak cocok dengan kontennya. Server tidak bisa mengendus body dan menimpanya.
• 415 Unsupported Media Type: resource tidak mendukung format kueri tersebut.
• 422 Unprocessable Content: formatnya baik-baik saja tetapi kueri tidak dapat dijalankan, misalnya SQL yang menyebut tabel yang tidak ada.
• 406 Not Acceptable: klien meminta tipe respons yang tidak dapat dihasilkan oleh resource.

Location dan Content-Location

Server dapat mengembalikan dua header opsional yang mengubah QUERY menjadi sesuatu yang bisa Anda GET nanti:

• Content-Location menunjuk ke hasil tersimpan dari eksekusi spesifik ini. Hasilnya mungkin bersifat sementara.
• Location menunjuk ke kueri tersimpan itu sendiri. GET pada URI tersebut akan menjalankan ulang kueri dengan data terbaru, tanpa mengirim ulang body-nya.

RFC menyarankan klien beralih ke GET pada URI Location untuk permintaan berulang, karena caching GET lebih sederhana. Jika Anda mengembalikan salah satu header tersebut untuk kueri dengan data sensitif, URI tersebut TIDAK BOLEH berisi bagian sensitif dari body aslinya.

Caching

Respons QUERY dapat di-cache. Cache key HARUS menyertakan konten permintaan dan metadata terkait seperti media type. Cache BOLEH menormalkan body terlebih dahulu, misalnya dengan menghapus content encoding atau menormalkan JSON untuk tipe +json, agar lebih banyak hit. Spesifikasi memperingatkan bahwa normalisasi yang buruk dapat mengembalikan respons yang salah, jadi perkirakan CDN akan berhati-hati di sini.

Redirect

301, 302, 307, atau 308 berarti “kirim QUERY yang sama ke URI baru”. Berbeda dengan POST, QUERY tidak boleh ditulis ulang menjadi GET pada 301 atau 302. 303 See Other berarti “ambil hasilnya dengan GET pada URI ini”.

Header Accept-Query

Accept-Query adalah header respons baru yang mengumumkan dukungan QUERY dan format kueri yang diterima suatu resource. Ini adalah daftar Structured Field, jadi parsing-lah sebagai daftar:

Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"

Klien juga dapat menemukan dukungan tersebut dengan OPTIONS dan membaca header Allow, atau cukup mengirim QUERY dan menangani 405 Method Not Allowed.

Alat mana yang mendukung QUERY saat ini?

Dukungannya tidak merata, jadi ujilah stack Anda sendiri. Berikut yang kami konfirmasi pada 28 Oktober 2026:

Berikut panggilan curl yang kami gunakan terhadap server Node lokal:

curl -i -X QUERY http://localhost:3000/products \
  -H "Content-Type: application/json" \
  -d '{"q":"running shoe","limit":2}'

Fetch Standard hanya melarang body pada GET dan HEAD, sehingga browser dapat mengirim QUERY dengan body. Namun, QUERY bukan metode yang masuk dalam CORS-safelist, jadi setiap QUERY lintas origin memicu preflight. Server Anda harus mencantumkan QUERY di Access-Control-Allow-Methods.

Celahnya ada di tengah jaringan: reverse proxy, API gateway, WAF, dan CDN yang membuat allowlist metode atau tidak menggunakan body sebagai kunci cache-nya. Periksa setiap hop sebelum Anda merilis. Buletin APIs You Won’t Hate mencatat bahwa banyak framework web sudah menangani QUERY secara langsung atau melalui routing metode kustom.

Cara mengadopsi QUERY tanpa merusak klien

Anda tidak perlu mencabut endpoint pencarian POST Anda.

1. Tambahkan QUERY di samping rute POST. Arahkan keduanya ke handler yang sama. Klien baru menggunakan QUERY; klien lama tetap berfungsi.
2. Umumkanlah. Kembalikan Accept-Query pada resource dan sertakan QUERY dalam Allow pada respons OPTIONS dan 405.
3. Tegakkan Content-Type. Kembalikan 400 atau 415 seperti yang direkomendasikan RFC, dan 422 untuk kueri yang bisa di-parse tetapi tidak dapat dijalankan.
4. Gunakan fallback ke 405 atau 501. Klien harus mencoba ulang body yang sama sebagai POST ketika ada hop yang menolak QUERY.
5. Perbaiki CORS. Tambahkan QUERY ke Access-Control-Allow-Methods untuk klien browser.
6. Putuskan soal caching. Aktifkan shared caching hanya jika cache Anda menggunakan body sebagai kunci. Jika tidak, kembalikan URI Location dan biarkan klien mengambilnya dengan GET.
7. Dokumentasikan. Di OpenAPI 3.2, definisikan operasinya di bawah query: pada path item:

openapi: 3.2.0
paths:
  /products:
    query:
      summary: Search products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductQuery'
      responses:
        '200':
          description: Matching products

Filter yang pendek dan sederhana bisa tetap berupa query string pada GET. RFC 10008 sendiri menyatakan bahwa jika kueri Anda sesingkat itu, GET mungkin pilihan yang lebih baik.

Biarkan coding agent Anda menguji endpoint QUERY dengan Apidog CLI

Metode baru berarti memeriksa happy path, setiap kode error, dan rute fallback. Serahkan itu ke Claude Code, Codex, atau Cursor dan biarkan ia menjalankan Apidog CLI.

Pasang CLI, login, dan tambahkan skill Apidog ke agen Anda:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Lalu berikan satu prompt kepada agen Anda:

In Apidog project <projectId>, add a QUERY /products endpoint that takes a
JSON body {q, limit}. Create test cases that assert 200 with an array for a
valid body, 415 for Content-Type text/plain, and 400 with no Content-Type.
Run them against the staging environment and summarize any failures.

Agen membaca setiap skema, memvalidasi payload-nya, dan baru kemudian menulis:

apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

File endpoint.json yang ditulisnya menetapkan "method": "query", yang dicantumkan oleh skema endpoint-create milik CLI bersama get, post, dan metode-metode WebDAV. Tambahkan --upload-report untuk melihat hasil run di aplikasi Apidog. Perintah apidog run yang sama dengan -r junit bisa langsung dipakai di CI; lihat cara menjalankan pengujian API di CI dengan apidog run dan cara menggunakan Apidog CLI di Claude Code. Paket Free Apidog mencakup hingga 4 pengguna.

FAQ

Apakah metode HTTP QUERY merupakan standar resmi? Ya. RFC 10008 adalah RFC Standards Track, Proposed Standard yang diterbitkan pada Juni 2026, dan IANA mencantumkan QUERY di HTTP Method Registry sebagai aman dan idempoten.

Apakah QUERY hanya GET dengan body? Hampir, tetapi QUERY didefinisikan lebih baik. RFC 9110 tidak memberikan semantik apa pun pada body GET, sehingga perantara dapat mengabaikan atau menolaknya. QUERY menjadikan body sebagai kueri, mewajibkan Content-Type, dan memasukkan body ke dalam cache key.

Kapan saya harus menggunakan QUERY alih-alih POST? Gunakan QUERY untuk pencarian atau filter hanya-baca apa pun yang terlalu besar atau terlalu sensitif untuk dimasukkan ke URL. Pertahankan POST untuk permintaan yang membuat atau mengubah sesuatu.

Bisakah browser mengirim permintaan QUERY? Bisa, melalui fetch dengan metode kustom. Permintaan QUERY lintas origin selalu memerlukan preflight CORS, jadi server Anda harus mengizinkan metode tersebut.

Apakah respons QUERY di-cache? Bisa. Cache harus menyertakan body permintaan beserta metadatanya dalam cache key. Banyak CDN dan proxy belum melakukannya, jadi periksa milik Anda atau kembalikan URI Location yang bisa di-GET oleh klien.

Apakah OpenAPI mendukung QUERY? OpenAPI 3.2 menambahkan field query ke Path Item Object untuk operasi QUERY, sehingga Anda dapat mendokumentasikannya tanpa ekstensi.