HTTP'ye yeni bir metot: QUERY neyi çözüyor?
Yıllardır bir API'de karmaşık bir arama ya da filtreleme yapmanın iki yolu vardı ve ikisi de bir yerinden aksıyordu. Filtreyi URL'nin sorgu dizesine (query string) sığdırmaya çalışırsanız uzunluk sınırlarına ve çirkin bir kodlamaya takılırsınız; gövdeye (body) taşımak için POST kullanırsanız da bu kez yaptığınız "okuma" işi, HTTP'nin gözünde bir "değiştirme" gibi görünür — önbelleğe alınamaz, güvenle tekrarlanamaz. Haziran 2026'da yayımlanan RFC 10008 bu boşluğu kapatan yeni bir HTTP metodu getirdi: QUERY. Kısaca "gövdesi olan bir GET" diyebilirsiniz — hem safe hem idempotent, ama gövdesinde istediğiniz kadar zengin bir sorgu taşıyabiliyor. Bu yazıda QUERY'nin çözdüğü sorunu, tam olarak ne vaat ettiğini, yanıtının nasıl önbelleğe alındığını ve bugün pratikte nerede işinize yarayacağını sade bir dille ele alacağız.
GET ile POST arasındaki boşluk neydi?
Bir HTTP metodunun iki önemli özelliği vardır. Bir metot safe ise sunucunun durumunu değiştirmeyi amaçlamaz — salt okumadır. Idempotent ise aynı isteği bir kez ya da beş kez göndermek aynı sonucu verir; bu da bir isteğin ağ hatasında güvenle yeniden denenebilmesi demektir. GET her ikisidir de: bu yüzden yanıtları önbelleğe alınabilir, tarayıcılar ve ara katmanlar (proxy, CDN) onu rahatça yeniden deneyebilir. Ama GET'in bir kısıtı vardır — sorgunuzu yalnızca URL'nin içine koyabilirsiniz.
Sorgunuz basit bir ?q=kitap olduğunda sorun yok. Ama onlarca alanlı bir filtre, iç içe bir yapı ya da bir coğrafi çokgen taşımanız gerektiğinde URL çabucak yetersiz kalır: pratikte güvenilir bir uzunluk sınırı vardır, iç içe veriyi düz bir metne kodlamak kırılgandır ve hassas kriterler sunucu kayıtlarına (log) URL olarak düşer. Doğal refleks bu yükü gövdeye taşımaktır — ve gövde deyince akla POST gelir. Ne var ki POST ne safe ne idempotenttir; anlamı "bu içeriği işle, durumu değiştirebilir" demektir. Sonuç: yaptığınız aslında bir okuma olsa bile yanıt önbelleğe alınmaz, ara katman isteği güvenle tekrarlayamaz ve niyetiniz protokol düzeyinde yanlış okunur.
safe idempotent cacheable gövde
GET ✓ ✓ ✓ ✗ (URL)
POST ✗ ✗ ~ ✓
QUERY ✓ ✓ ✓ ✓
# QUERY = GET'in güvenceleri + POST'un gövdesiQUERY tam olarak ne yapıyor?
QUERY, sunucudan gövdedeki içeriği safe ve idempotent biçimde işlemesini ve sonucunu döndürmesini ister. Yani sorgunuzu — bir JSON filtresi, bir SQL benzeri ifade, bir GraphQL sorgusu, bir SPARQL bloğu, ne olursa — isteğin gövdesine koyarsınız; sunucu bunu bir okuma olarak ele alır ve karşılığında sonucu verir. Kritik ayrım şudur: POST'un aksine QUERY isteği, kısmi bir durum değişikliği kaygısı olmadan otomatik olarak yeniden denenebilir ya da baştan başlatılabilir. Böylece bir arama isteği, bir bağlantı koptuğunda güvenle tekrarlanır.
QUERY /siparisler HTTP/1.1
Host: api.ornek.com
Content-Type: application/json
# zengin filtre, URL'ye değil gövdeye
{ "durum": ["hazir", "kargoda"],
"tutar": { "min": 100, "max": 5000 },
"sirala": "-tarih", "limit": 50 }
# yanıt: bir okuma sonucu, önbelleklenebilir
HTTP/1.1 200 OK
Content-Location: /siparisler?kayitli=8f2a
Yanıt nasıl önbelleğe alınıyor?
QUERY'nin en değerli tarafı yanıtının cacheable olmasıdır — ama bunun bir inceliği var. GET'te önbellek anahtarı (cache key) esasen URL'dir; aynı URL, aynı yanıt. QUERY'de ise sorgu gövdede durduğu için önbellek anahtarının gövdeyi ve ilgili meta veriyi de kapsaması gerekir. RFC'nin de belirttiği gibi bu, GET yanıtlarını önbelleğe almaktan doğası gereği daha karmaşıktır: ara katmanın isteği anahtarlayabilmek için gövdenin tamamını okuması gerekir. Bu yüzden bugün çoğu genel amaçlı önbellek katmanı ve CDN, gövdeye göre anahtarlamayı henüz kutudan çıktığı gibi yapmaz.
Standart burada zarif bir köprü sunuyor: sunucu, yanıtında bir Content-Location başlığı döndürerek "bu sorgunun sonucuna şu URL'den GET ile de ulaşabilirsin" diyebilir. Böylece pahalı sorgu bir kez QUERY ile çalışır, sonucu sıradan bir GET kaynağı gibi paylaşılabilir ve önbelleklenebilir bir adrese bağlanır. QUERY'nin esnekliği ile GET'in olgun önbellek altyapısı bu başlıkla birbirine değer.
Bunu pratikte nerede kullanırsınız?
QUERY, "aslında bu bir okuma ama POST kullanmak zorunda kaldım" dediğiniz her yere oturuyor. En net örnekler şunlar:
- Karmaşık arama ve filtreleme API'leri — onlarca alanlı filtreleri, aralıkları ve sıralama kurallarını URL'ye sıkıştırmak yerine gövdeye taşıyıp yine de safe/cacheable bir okuma olarak sunarsınız.
-
GraphQL ve sorgu dilleri — okuma sorguları bugün çoğunlukla
POST /graphqlile taşınıyor ve bu yüzden HTTP düzeyinde önbelleklenmesi zor. QUERY, bu okumalara doğru semantiği verir. Konunun temeli için GraphQL & API Sorgu Dilleri rehberimize bakabilirsiniz. - Büyük veya hassas parametreler — coğrafi çokgenler, uzun kimlik listeleri ya da URL loglarında görünmesini istemediğiniz kriterler gövdede daha doğru bir yer bulur.
Bugün güvenle kullanabilir misiniz?
QUERY yeni bir fikir değil; kökeni 2015'teki bir taslağa (o zamanki adıyla SEARCH) uzanıyor, 2021'de IETF HTTP çalışma grubunca benimsendi ve uzun bir olgunlaşmanın ardından Haziran 2026'da RFC 10008 olarak Proposed Standard seviyesinde yayımlandı. Yani artık "deneysel bir öneri" değil, resmi bir standart. Yine de her yeni HTTP metodunda olduğu gibi asıl mesele uçtan uca destek: sunucu çatınız, istemci kütüphaneleriniz ve aradaki her proxy/CDN/WAF katmanının QUERY'yi tanıması zaman alır. Bilinmeyen bir metodu bazı ara katmanlar hâlâ engelleyebilir.
Bu yüzden en sağlıklı yol kademeli geçiş: yeni okuma uçlarını QUERY'ye göre tasarlayın ama desteklemeyen istemciler için POST'a düşen bir yol bırakın; hangi metodun kullanıldığını tek bir soyutlama katmanında tutun ki ekosistem olgunlaştıkça geçiş yüzlerce dosyaya değil tek bir yere dokunmak olsun. Bu, HTTP/3'e geçişte işleyen aynı temkinli yaklaşımdır: yeni ve daha doğru olanı benimserken eskisini bir süre yanınızda taşımak.
Peki ne değişiyor?
QUERY tek başına çığır açan bir yenilik değil; daha çok, HTTP'nin yıllardır taşıdığı bir tutarsızlığı düzelten sessiz ama doğru bir hamle. Web'in en yaygın işlerinden biri olan "karmaşık bir okuma" nihayet kendi metoduna kavuştu — URL'nin dar kalıbına sıkışmadan, POST'un yanlış anlamını üstlenmeden. Üzerine API kuran ekipler için pratik kazanım net: aynı işi hem esnek hem önbelleklenebilir hem de güvenle tekrarlanabilir yapabilmek.
Konunun temellerine daha yakından bakmak isterseniz Bilgi Merkezi · Ağ Temelleri & Protokoller, API Tasarımı & Entegrasyon ve GraphQL & API Sorgu Dilleri rehberlerine göz atabilirsiniz. Metodun resmi tanımı için RFC 10008 — The HTTP QUERY Method belgesine bakabilirsiniz.