HTTP QUERY metodu, karmaşık salt-okunur sorguları istek gövdesine taşıyor

dev.to'da yayımlanan bir rehber, HTTP QUERY metoduna pratik bir giriş sunuyor; bu görece yeni fiil, API geliştiricilerine her parametreyi URL'e doldurmadan karmaşık salt-okunur sorgular çalıştırmak için özel bir yol sağlıyor.

QUERY ne yapar

dev.to'daki yazının anlattığı gibi, QUERY yalnızca veri okuyan, ancak sorgunun kendisinin istek gövdesinde yer aldığı istekler için tasarlanmış. Basit bir arama hâlâ query string içeren bir GET olarak sorunsuz çalışıyor; örneğin kullanıcıları şehre ve yaşa göre filtrelemek gibi. Sorun, sürekli büyüyen isteklerde: birden fazla filtre, sıralama kuralları, sayfalama, tarih aralıkları ve diğer koşullar tek bir URL'e üst üste ekleniyor ve URL uzun ve yönetilmesi zahmetli hâle geliyor.

QUERY ile aynı bilgiler yapılandırılmış veri olarak yolculuk yapıyor:

QUERY /users Content-Type: application/

{ "city": "Noida", "minAge": 25, "sort": "name", "limit": 20 }

Sunucu, aşırı yüklenmiş bir query string'i ayrıştırmak yerine düzgün biçimlendirilmiş bir sorgu nesnesi alıyor.

GET ve POST'tan farkı

Makale, QUERY'yi geliştiricilerin geleneksel olarak bel bağladığı iki metotla karşılaştırıyor. GET, kısa bir query string'in yeterli olduğu basit okumalar için doğru araç olmaya devam ediyor. Karmaşık aramalarda ise birçok ekip /users/search gibi bir endpoint'e POST yapmaya başvuruyordu; ancak POST geleneksel olarak sunucu durumunu değiştirebilecek bir işlemi ifade ettiğinden, bu kalıp anlamsal olarak belirsiz hâle geliyor.

QUERY tam olarak güvenli ve idempotent sorgulama için tasarlandı; böylece her metoda net bir görev tanımı geliyor:

• Basit okumalar için GET
• Karmaşık veya büyük okumalar için QUERY
• Durum oluşturmak veya başka şekilde değiştirmek için POST

Gerçekçi bir örnek

Rehberdeki analitik senaryosu, metodun hakkını nerede verdiğini gösteriyor. Veriyi tarih aralığına, ülkeye, duruma ve diğer koşullara göre filtreleyen, ardından sıralama ve sayfalama uygulayan bir uygulama, tek bir yapılandırılmış gövde gönderebilir:

QUERY /analytics Content-Type: application/

{ "dateRange": { "from": "2026-01-01", "to": "2026-09-30" }, "filters": { "country": ["IN", "US"], "status": ["active", "pending"] }, "sort": { "revenue": "desc" } }

İstemci, devasa bir URL oluşturmak yerine iç içe geçmiş bir nesne gönderiyor ve sunucu bunu işleyerek istenen veriyi döndürüyor.

Araçlar henüz her yerde hazır değil

QUERY yeni olduğu için dev.to makalesi, API istemcileri, framework'ler, proxy'ler ve diğer araçlardaki desteğin düzensiz olduğu konusunda uyarıyor. Örneğin Postman'ın bazı sürümleri, metodun açılır listesinde QUERY'yi göstermiyor. Bir arayın arayüzünde görünmemesi, metodun var olmadığı anlamına gelmiyor; yalnızca o aracın henüz bunun için destek geliştirmediği anlamına geliyor. Daha fazla okuma için rehber, HTTP QUERY metodunu kapsayan spesifikasyon olan RFC 10008'e ve MDN'nin dokümantasyonuna dikkat çekiyor.

Neden önemli

QUERY, API geliştiricilerinin yıllardır doğaçlama yaptıkları bir geçici çözümü standartlaştırıyor. POST gövdelerini kabul eden arama endpoint'leri yaygındı, ancak okuma ile yazma arasındaki çizgiyi bulandırıyorlardı; tasarımı gereği güvenli ve idempotent olan bir metod bu belirsizliği ortadan kaldırıyor ve karmaşık sorgulara URL dışında birinci sınıf, yapılandırılmış bir yuva veriyor.

API tasarllayan ya da sürdüren herkes için dev.to rehberinden çıkarılacak pratik ders net: basit aramalarda GET kullanmaya devam edin, sorgu karmaşıklaştığında veya büyüdüğünde QUERY'ye uzanın ve uygulamaya geçmeden önce istemcilerinizin, framework'lerinizin ve araçlarınızın bu metodu gerçekten desteklediğini doğrulayın.