HTTP QUERY Metodu Nedir? RFC 10008, QUERY vs GET vs POST

HTTP QUERY yöntemi, RFC 10008'de (Haziran 2026) tanımlanan, sorguyu istek gövdesinde gönderen ve hem güvenli hem de idempotent olan yeni bir istek yöntemidir. Onu gövdeli GET gibi düşünün: POST'un karmaşık filtreler için sunduğu alanı ve GET'in önbellekleme ile otomatik yeniden denemeler için sağladığı garantileri elde edersiniz.

Apidog'u bugün deneyin

URL'ye 3 KB'lık bir filtre tıkıştırdıysanız veya salt okunur bir aramayı POST olarak gönderip önbelleğinizin ve yeniden deneme mantığınızın bunu yok saydığını gördüyseniz, QUERY çözümdür. Bu kılavuz, spesifikasyonun ne söylediğini, QUERY'nin GET ve POST ile nasıl karşılaştırıldığını, bugün nelerin desteklediğini ve kodlama ajanınızla bir QUERY uç noktasını nasıl test edeceğinizi kapsar.

HTTP QUERY yöntemi nedir?

QUERY, hedef kaynaktan istek içeriğinde tanımlanan sorguyu çalıştırmasını ve sonucu döndürmesini isteyen bir HTTP yöntemidir. İstek gövdesi ve Content-Type sorguyu tanımlar. Yöntem güvenlidir (istemci durum değişikliği beklemez) ve idempotenttir (tekrarlanması aynı etkiyi yapar), böylece istemciler, proxy'ler ve önbellekler onu GET gibi yeniden deneyebilir ve önbelleğe alabilir.

Spesifikasyon, Julian Reschke (greenbytes), James M. Snell (Cloudflare) ve Mike Bishop (Akamai) tarafından Haziran 2026'da yayımlanan Önerilen Standart RFC 10008, "HTTP QUERY Yöntemi" belgesidir. IANA, onu HTTP Yöntem Kaydı'na "güvenli: evet, idempotent: evet" olarak ekledi; neredeyse olacağı WebDAV dönemi SEARCH yönteminin hemen yanına.

Bir QUERY isteği şöyle görünür:

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

Sunucu, 200 OK ve gövdede sonuçla yanıt verir.

GET ve POST neden yeterli değildi

QUERY'den önce karmaşık bir okuma için iki seçeneğiniz vardı ve ikisi de sızıntı yapar.

GET her şeyi URL'ye koyar. RFC 10008 bununla ilgili dört sorun sıralar:

1. Boyut sınırları önceden bilinmez, çünkü bir istek birçok sistemden geçer. RFC 9110 yalnızca göndericilerin ve alıcıların en az 8.000 okteti desteklemesini önerir.
2. Yapılandırılmış veriyi geçerli bir URI'ye kodlamak israftır.
3. URI'ler, istek gövdelerinden çok daha sık günlüğe kaydedilir ve yer imlerine eklenir; bu da hassas filtreler için gizlilik sorunudur.
4. Sorgu girdilerinin her kombinasyonu kendi kaynağı haline gelir.

Gövdeli GET de cevap değildir. RFC 9110, bir GET isteğindeki içeriğin tanımlı anlambilimi olmadığını söyler. Bazı sunucular onu okur, bazıları atar ve bazı proxy'ler isteği reddeder. Yol boyunca ona güvenemezsiniz.

POST çalışır, ancak niyet hakkında yalan söyler. Bir POST araması sorunsuz çalışır, yine de hiçbir şey bir istemciye, önbelleğe, proxy'ye veya yeniden deneme kitaplığına işlemin salt okunur olduğunu söylemez. Bu yüzden önbellekler onu atlar ve istemciler bağlantı düştükten sonra onu yeniden denemez. Yalnızca yeniden denemeleri güvenli hale getirmek için saf bir okumaya idempotency anahtarı eklemek zorunda kaldıysanız, bunu hissetmişsinizdir.

QUERY, POST'un gövdesini korur ve GET'in garantilerini ekler.

QUERY vs GET vs POST

İşte RFC 10008'in Tablo 1'ine dayanan karşılaştırma:

Özellik	GET	QUERY	POST
Güvenli	Evet	Evet	Potansiyel olarak hayır
Idempotent	Evet	Evet	Potansiyel olarak hayır
İstek gövdesi	Tanımlı anlambilim yok	Beklenir, sorguyu tanımlar	Beklenir
Sorgunun kendisi için URI	Evet, tanım gereği	İsteğe bağlı, Location ile	Hayır
Sonuç için URI	İsteğe bağlı, Content-Location ile	İsteğe bağlı, Content-Location ile	İsteğe bağlı, Content-Location ile
Önbelleğe alınabilir	Evet	Evet, gövde önbellek anahtarının parçasıdır	Yalnızca sonraki GET veya HEAD için
Tarayıcılardan CORS preflight	Basit istekler için değil	Her zaman	Basit istekler için değil

Kısa versiyon: sorgu URL'ye rahatça sığıyorsa GET, sığmıyorsa QUERY ve yalnızca istek durumu değiştiriyorsa POST kullanın. Klasik yöntemler hakkında bir hatırlatma için HTTP yöntemleri ve GET vs POST kılavuzlarımıza bakın.

RFC 10008 ne tanımlar

Content-Type zorunludur

Sunucular, Content-Type'ı eksik veya gövdeyle tutarsız olan bir QUERY'yi BAŞARISIZ bırakMALIDIR. RFC şu durum kodlarını önerir:

• 400 Bad Request: medya türü yok veya içerikle eşleşmeyen bir tür var. Sunucular gövdeyi koklayıp bunu geçersiz kılamaz.
• 415 Unsupported Media Type: kaynak bu sorgu biçimini desteklemiyor.
• 422 Unprocessable Content: biçim uygun ancak sorgu çalıştırılamıyor; örneğin SQL, var olmayan bir tabloyu adlandırıyor.
• 406 Not Acceptable: istemci, kaynağın üretemeyeceği bir yanıt türü istedi.

Location ve Content-Location

Bir sunucu, QUERY'yi daha sonra GET'leyebileceğiniz bir şeye dönüştüren iki isteğe bağlı başlık döndürebilir:

• Content-Location, bu belirli çalıştırmanın saklanan sonucuna işaret eder. Geçici olabilir.
• Location, saklanan sorgunun kendisine işaret eder. Bunun üzerinde bir GET, gövdeyi yeniden göndermeden sorguyu güncel verilerle yeniden çalıştırır.

RFC, GET önbelleklemesi daha basit olduğu için istemcilerin tekrarlanan isteklerde Location URI'si üzerinden GET'e geçmesini önerir. Hassas veri içeren bir sorgu için bu başlıklardan birini döndürürseniz, URI orijinal gövdenin hassas kısımlarını İÇERMEMELİDİR.

Önbellekleme

QUERY yanıtları önbelleğe alınabilir. Önbellek anahtarı, istek içeriğini ve medya türü gibi ilgili meta verileri İÇERMELİDİR. Önbellekler daha fazla isabet elde etmek için önce gövdeyi normalleştirebilir; örneğin içerik kodlamasını kaldırarak veya bir +json türü için JSON'u normalleştirerek. Spesifikasyon, kötü normalleştirmenin yanlış yanıt döndürebileceği konusunda uyarır, bu yüzden CDN'lerin burada dikkatli olmasını bekleyin.

Yönlendirmeler

301, 302, 307 veya 308, "aynı QUERY'yi yeni URI'ye gönder" anlamına gelir. POST'un aksine, bir QUERY 301 veya 302'de GET'e yeniden yazılmamalıdır. 303 See Other, "sonucu bu URI üzerinde bir GET ile al" anlamına gelir.

Accept-Query başlığı

Accept-Query, QUERY desteğini ve bir kaynağın kabul ettiği sorgu biçimlerini duyuran yeni bir yanıt başlığıdır. Bu bir Yapılandırılmış Alan listesidir, bu yüzden onu öyle ayrıştırın:

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

İstemciler ayrıca OPTIONS ile desteği keşfedip Allow başlığını okuyabilir veya doğrudan QUERY gönderip bir 405 Method Not Allowed yanıtını işleyebilir.

Bugün hangi araçlar QUERY'yi destekliyor?

Destek dengesiz, bu yüzden kendi yığınınızı test edin. 28 Ekim 2026'da doğruladıklarımız şunlardır:

Araç	Sonuç
Node.js 24 http sunucusu
curl 8.7	-d ile curl -X QUERY, yöntemi ve gövdeyi gönderdi
Python 3.14 http.client	Gövdeli bir QUERY gönderdi
OpenAPI 3.2	Path Item Object, QUERY işlemleri için bir query alanına sahiptir
Apidog CLI 2.2.12	endpoint-create şeması "method": "query" değerini kabul eder

Yerel bir Node sunucusuna karşı kullandığımız curl çağrısı şöyledir:

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

Fetch Standard yalnızca GET ve HEAD'de gövdeyi yasaklar, bu yüzden tarayıcılar QUERY'yi gövdeli gönderebilir. Ancak QUERY, CORS-safelisted bir yöntem değildir, bu yüzden her çapraz kaynaklı QUERY bir preflight tetikler. Sunucunuz Access-Control-Allow-Methods içinde QUERY listelemelidir.

Boşluklar ağın ortasındadır: yöntemleri izin listesine alan veya önbelleğini gövdeye göre anahtarlamayan ters proxy'ler, API ağ geçitleri, WAF'ler ve CDN'ler. Yayına almadan önce her atlamayı kontrol edin. APIs You Won't Hate bülteni, birçok web çerçevesinin QUERY'yi doğrudan veya özel yöntem yönlendirmesiyle zaten işlediğini belirtiyor.

İstemcileri bozmadan QUERY'yi nasıl benimsersiniz

POST arama uç noktalarınızı söküp atmanız gerekmez.

1. QUERY'yi POST rotasının yanına ekleyin. İkisini de aynı işleyiciye yönlendirin. Yeni istemciler QUERY kullanır; eskileri çalışmaya devam eder.
2. Duyurun. Kaynakta Accept-Query döndürün ve OPTIONS ile 405 yanıtlarında Allow içine QUERY ekleyin.
3. Content-Type'ı zorunlu kılın. RFC'nin önerdiği gibi 400 veya 415 döndürün ve ayrıştırılan ancak çalıştırılamayan sorgular için 422 döndürün.
4. 405 veya 501'de geri düşün. Bir atlama QUERY'yi reddettiğinde istemciler aynı gövdeyi POST olarak yeniden denemelidir.
5. CORS'u düzeltin. Tarayıcı istemcileri için Access-Control-Allow-Methods içine QUERY ekleyin.
6. Önbellekleme konusunda karar verin. Paylaşımlı önbellekleme yalnızca önbelleğiniz gövdeye göre anahtarlıyorsa etkinleştirin. Aksi halde bir Location URI'si döndürün ve istemcilerin onu GET'lemesine izin verin.
7. Belgeleyin. OpenAPI 3.2'de işlemi path item üzerindeki query: altında tanımlayın:

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

Kısa, basit filtreler GET üzerinde sorgu dizileri olarak kalabilir. RFC 10008'in kendisi, sorgunuz bu kadar kısaysa GET'in muhtemelen daha iyi seçim olduğunu söyler.

Kodlama ajanınızın Apidog CLI ile bir QUERY uç noktasını test etmesine izin verin

Yeni bir yöntem, mutlu yolu, her hata kodunu ve geri dönüş rotasını kontrol etmek anlamına gelir. Bunu Claude Code, Codex veya Cursor'a verin ve Apidog CLI'yı kullanmasına izin verin.

CLI'yi kurun, oturum açın ve ajanınıza Apidog becerisini ekleyin:

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

Ardından ajanınıza bir istem verin:

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.

Ajan her şemayı okur, yükünü doğrular ve ancak ondan sonra şunları yazar:

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

Yazdığı endpoint.json, "method": "query" değerini ayarlar; CLI'nin endpoint-create şeması bunu get, post ve WebDAV yöntemleriyle birlikte listeler. Çalıştırmayı Apidog uygulamasında görmek için --upload-report ekleyin. -r junit ile aynı apidog run komutu CI'ya girer; apidog run ile CI'da API testleri nasıl çalıştırılır ve Apidog CLI, Claude Code'da nasıl kullanılır sayfalarına bakın. Apidog'un Ücretsiz planı 4 kullanıcıya kadar kapsar.

SSS

HTTP QUERY yöntemi resmi bir standart mı? Evet. RFC 10008, Haziran 2026'da yayımlanan bir Standards Track, Proposed Standard RFC'dir ve IANA, QUERY'yi HTTP Yöntem Kaydı'nda güvenli ve idempotent olarak listeler.

QUERY sadece gövdeli GET mi? Yakın, ancak daha iyi tanımlanmıştır. RFC 9110 bir GET gövdesine anlambilim vermez, bu yüzden aracılar onu yok sayabilir veya reddedebilir. QUERY, gövdeyi sorgu yapar, bir Content-Type gerektirir ve gövdeyi önbellek anahtarına dahil eder.

POST yerine ne zaman QUERY kullanmalıyım? Bir URL için çok büyük veya çok hassas olan her salt okunur arama veya filtre için QUERY kullanın. Bir şey oluşturan veya değiştiren istekler için POST'u saklayın.

Tarayıcılar QUERY istekleri gönderebilir mi? Evet, özel bir yöntemle fetch aracılığıyla. Çapraz kaynaklı QUERY istekleri her zaman bir CORS preflight gerektirir, bu yüzden sunucunuz yönteme izin vermelidir.

QUERY yanıtları önbelleğe alınır mı? Alınabilir. Önbellekler, istek gövdesini ve meta verilerini önbellek anahtarına dahil etmelidir. Birçok CDN ve proxy bunu henüz yapmıyor, bu yüzden kendinizinkini kontrol edin veya istemcilerin GET'leyebileceği bir Location URI'si döndürün.

OpenAPI QUERY'yi destekliyor mu? OpenAPI 3.2, QUERY işlemleri için Path Item Object'e bir query alanı ekler, böylece onları uzantı olmadan belgeleyebilirsiniz.