HTTP'nin sonunda bir QUERY metodu var. Bugün nelerin çalıştığını bulmak için bir saat harcadım

19 Temmuz 2026· Hüseyin Çınar

Sayamayacağım kadar çok arama endpoint’i yazdım. İşe alım platformunda aday arama, araç pazaryerinde kayıtlı aramalarla galeri ilanı filtreleri, IoT panelinde telemetri sorguları. Ve her seferinde, tasarım aşamasında aynı rahatsız edici seçim çıkar; her seferinde de önünüzde tam olarak üç kötü seçenek vardır.

Birinci seçenek: query string’li GET. Filtre nesnesi büyüyene kadar harika çalışır. On beş filtreli, sıralamalı, sayfalamalı bir kayıtlı aramanın URL’de işi yok. Uzunluk sınırlarına çarparsınız, encoding’le boğuşursunuz ve her şey erişim loglarına düşer.

İkinci seçenek: gövdeli GET. Bunu Elasticsearch meşhur etti ve o günden beri insanları üzüyor. Eski HTTP spesifikasyonları GET gövdesinin ne anlama geldiğini hiç söylemedi; istemciler, proxy’ler ve yük dengeleyiciler kendi davranışını kendi seçti - kimi düşürür, kimi iletir, kimi isteği komple reddeder. Kimsenin üzerinde anlaşmadığı semantiğin üstüne bina kuramazsınız.

Üçüncü seçenek: POST /search. Benim de yıllardır yaptığım şey, neredeyse herkes gibi. Çalışıyor. Ama aynı zamanda küçük bir yalan. Arama güvenli ve tekrarlanabilir bir iştir - sunucuda hiçbir şeyi değiştirmez - ama POST, aradaki her katmana bunun tam tersini söyler. Ortak önbellek yok. Kopan bağlantıda otomatik yeniden deneme yok; çünkü proxy, bir POST’un yan etkisi olabileceğini varsaymak zorunda. Sırf gövde gönderebilmek için HTTP’nin gerçek ve işe yarar davranışlarından vazgeçersiniz.

Geçen ay bu “zehrini seç” durumu sona erdi. RFC 10008 - on dört taslak revizyonundan sonra Haziran 2026’da yayınlandı - QUERY metodunu tanımlıyor: POST gibi gövdesi olan ama GET gibi açıkça güvenli ve idempotent bir istek - üstelik yanıtları önbelleklenebilir. “İstediğim şeyin karmaşık bir tarifi burada; bu hiçbir şeyi değiştirmiyor” cümlesinin eksik fiili tam olarak buydu.

QUERY /vehicles HTTP/1.1
Content-Type: application/json

{ "filters": { "fuel": "ev", "battery_health_min": 85 },
  "sort": "price_asc", "page": 3 }

Bugün gerçekten neler çalışıyor

Yeni bir RFC hakkında okumak başka şey. Ben 2026’da gerçekten bir QUERY isteği gönderince ne olduğunu merak ettim ve bir saatimi buna harcadım. Aşağıdakilerin hepsi kendi makinemden alınmış gerçek sonuçlar; dokümantasyondan değil.

Node.js 24: kutudan çıktığı gibi çalışıyor. http.METHODS listesi QUERY’yi birinci sınıf metot olarak içeriyor ve düz bir http.createServer onu herhangi bir istek gibi alıyor:

// sunucu logu: { method: 'QUERY', receivedBody: '{"filter":{"status":"active"}}' }
const server = http.createServer((req, res) => { /* req.method === 'QUERY' */ });

fetch: çalışıyor. Node’un yerleşik fetch’i (undici) method: 'QUERY' ile gövdeyi şikayetsiz gönderiyor. Fetch spesifikasyonu yalnızca CONNECT, TRACE ve TRACK’i yasaklıyor, QUERY geçiyor - ama ben yalnızca sunucu tarafı fetch’i doğruladım, her tarayıcıyı değil; tarayıcı desteğine “güvenmeden önce test et” muamelesi yapın.

curl: çalışıyor - özel metot zaten sadece curl -X QUERY --data ....

Cloudflare: olduğu gibi geçiriyor. Bu siteye - statik dosyaları sunan bir Cloudflare Worker’da koşuyor - bir QUERY isteği gönderdim. Yanıt temiz bir 405 Method Not Allowed oldu. Yani edge metoda takılmadı; handler’a kadar taşıdı, handler da haklı olarak “statik dosyada onun işi yok” dedi. Yepyeni bir fiil için asıl önemli kısım bu: metodun büyük bir CDN’den bozulmadan geçmesi.

ASP.NET Core: Henüz bir MapQuery() yardımcısı yok ama routing özel metotları zaten hep destekledi: endpoints.MapMethods("/search", ["QUERY"], handler) bugün çalışır.

Production’da kullanır mıyım?

Herkese açık bir API’de, henüz değil. RFC bir aylık; API gateway’lerin, WAF kurallarının, OpenAPI araçlarının ve istemci SDK üreticilerinin zamana ihtiyacı var. Kurumsal bir proxy’nin sessizce bozduğu bir arama endpoint’i, dürüst bir POST’tan daha kötüdür.

Ama iç API’lerde - servisten servise, admin panelleri, iki ucunu da benim kontrol ettiğim her yerde - şimdi başlamayı düşünüyorum. Yalnızca yeniden deneme semantiği bile buna değer: idempotent bir arama, bağlantı koptuğunda altyapı tarafından güvenle yeniden denenebilir - normalde elle inşa etmek zorunda kaldığınız türden bir dayanıklılık. Planım önce iç bir admin arama endpoint’inde kullanmak; dışarıya doğru yolunu kendisi kazansın.

Yirmi beş yıllık POST /search bir geçici çözümdü. Sonunda gerçek fiile kavuşmak güzel.