API tasarımının en bilindik geçici çözümlerinden biri nihayet sona erebilir. Yıllardır API tasarımcıları, karmaşık sorguları işlemek için GET ve POST arasında sıkışıp kalmıştı. GET ile başlayan temiz bir istek, zamanla iç içe geçmiş filtreler, sıralamalar ve kullanıcıya özgü kısıtlamalarla boğuşan bir URL canavarına dönüşüyordu. Çözüm olarak JSON gövdesiyle POST kullanmak yaygınlaştı, ancak bu da HTTP'nin temel semantiğini zedeliyordu. Haziran 2026'da yayımlanan RFC 10008 ile gelen QUERY yöntemi, bu soruna kalıcı bir çözüm sunuyor.
QUERY yöntemi, karmaşık okuma işlemleri için özel olarak tasarlanmıştır. GET'in güvenli (safe) ve önbelleklenebilir (cacheable) yapısını korurken, POST'un esneklik avantajını sunar. Bir QUERY isteği, hedef kaynağın kapsamında bir sorgu gerçekleştirilmesini talep eder. İstek gövdesi, sorgunun nasıl yapılacağını belirten bir sorgu dilini (örneğin JSONPath, SQL) içerir. Bu sayede URL'ler kısa ve temiz kalır, tüm karmaşıklık istek gövdesine taşınır.
GET ve POST arasındaki boşluğu dolduran QUERY, özellikle büyük ve karmaşık veri kümeleri üzerinde yapılan sorgulamalar için idealdir. GET, basit anahtar-değer çiftlerini sorgulamak için harikadır, ancak iç içe filtreler, diziler ve aralıklar içeren sorgular için yetersiz kalır. POST ise güvenli ve idempotent olmadığı için önbellekleme ve tekrar deneme gibi önemli HTTP özelliklerinden faydalanamaz. QUERY, bu iki yöntemin en iyi yönlerini birleştirir.
QUERY'nin en önemli özelliklerinden biri, güvenli (safe) ve idempotent olmasıdır. Bu, aynı sorgunun birden çok kez tekrarlanmasının sunucuda herhangi bir durum değişikliğine yol açmayacağı ve sonuçların önbelleğe alınabileceği anlamına gelir. Ayrıca, QUERY yanıtları HTTP önbellekleme kurallarına tabidir ve CDN'ler tarafından otomatik olarak önbelleğe alınabilir. Bu, performansı önemli ölçüde artırır.
RFC 10008, QUERY yönteminin kullanımını ayrıntılı olarak tanımlar. İstek gövdesinde Content-Type başlığı zorunludur ve bu başlık, sorgu dilini belirtir. Örneğin, application/jsonpath ile JSONPath ifadeleri kullanılabilir. Sunucu, geçersiz veya eksik Content-Type durumunda isteği reddetmelidir. Ayrıca, QUERY yanıtları için 200 (başarılı) ve 4xx/5xx hata kodları kullanılır. Özellikle 422 (İşlenemeyen Varlık) kodu, sorgu dilinin geçersiz olması durumunda döndürülür.
Detaylar ve Etkileri
QUERY'nin API tasarımına getirdiği yenilikler büyük. Artık geliştiriciler, karmaşık sorgular için POST kullanmak zorunda kalmayacak. Bu, API'lerin daha tutarlı ve anlaşılır olmasını sağlayacak. Ayrıca, QUERY ile birlikte gelen net semantik, API dokümantasyonunu ve istemci-sunucu etkileşimini basitleştirecek. Örneğin, bir arama API'si için QUERY /products endpoint'i kullanmak, hem GET'in basitliğini hem de POST'un esnekliğini sunar.
Sonuç olarak, QUERY yöntemi HTTP protokolüne önemli bir katkı sağlıyor. API tasarımcıları, artık karmaşık sorgular için GET ve POST arasında sıkışıp kalmayacak. QUERY, güvenli, idempotent ve önbelleklenebilir yapısıyla modern API'lerin ihtiyaçlarına cevap veriyor. RFC 10008 ile standartlaşan bu yöntem, önümüzdeki yıllarda API tasarımında yaygın olarak kullanılacak gibi görünüyor. Geliştiricilerin bu yeni yöntemi öğrenmesi ve uygulamalarına entegre etmesi, daha verimli ve ölçeklenebilir API'ler oluşturmalarına yardımcı olacak.
Kaynak: dev.to
