Query String (Sorgu Dizisi) Nedir?

URL'lerin sonunda bazen garip şeyler görürsünüz: soru işaretleri, eşittir işaretleri, & sembolleri... Bunlar query string (sorgu dizisi). API'lere ek bilgi göndermenin en yaygın yollarından biri.

Bu makalede query string'in ne olduğunu, nasıl yazıldığını ve ne zaman kullanıldığını öğreneceksiniz.

Query String Nedir?

Query string, URL'in sonuna eklenen anahtar-değer çiftleridir. Sunucuya ek bilgi göndermek için kullanılır.

Yapısı

https://api.example.com/arama?kelime=telefon&marka=samsung&limit=10
                              └─────────────── query string ───────────────┘

Parçaları:

• ? → Query string'in başlangıcı
• kelime=telefon → İlk anahtar-değer çifti
• & → Çiftleri ayıran sembol
• marka=samsung → İkinci çift
• limit=10 → Üçüncü çift

Temel Kurallar

Kural 1: Soru İşareti ile Başlar

https://site.com/sayfa?parametre=deger
                      ↑
                      Başlangıç

Kural 2: Anahtar=Değer Formatı

anahtar=değer
isim=ali
sayfa=3
siralama=fiyat

Kural 3: & ile Ayrılır

?birinci=1&ikinci=2&ucuncu=3

Kural 4: Boşluk ve Özel Karakterler Kodlanır

Boşluk ve özel karakterler URL'de doğrudan kullanılamaz. URL encoding yapılır:

Örnek:

Arama: "kırmızı ayakkabı"
URL: ?arama=k%C4%B1rm%C4%B1z%C4%B1%20ayakkab%C4%B1

Tarayıcı ve araçlar bu kodlamayı otomatik yapar, manuel yapmanız gerekmez.

Gerçek Hayat Örnekleri

Google Araması

Google'da "javascript öğren" araması yaptığınızda URL şöyle olur:

https://www.google.com/search?q=javascript+öğren

• q → Query (arama terimi) parametresi
• javascript+öğren → Aradığınız kelimeler

YouTube Videosu

Bir YouTube videosunun URL'i:

https://www.youtube.com/watch?v=dQw4w9WgXcQ

• v → Video ID parametresi
• dQw4w9WgXcQ → Videonun benzersiz ID'si

E-ticaret Filtreleme

Bir e-ticaret sitesinde filtreleme yaptığınızda:

https://magazam.com/urunler?kategori=elektronik&marka=apple&min_fiyat=5000&max_fiyat=20000&siralama=fiyat_artan

API'lerde Query String Kullanımı

Örnek 1: Arama

Çoğu API, arama için q veya query parametresi kullanır:

GET https://api.tvmaze.com/search/shows?q=breaking+bad

Yanıt: "Breaking Bad" ile eşleşen diziler

Örnek 2: Filtreleme

Belirli kriterlere göre veri filtreleme:

GET https://api.example.com/urunler?kategori=kitap&yazar=orhan+pamuk

Yanıt: Orhan Pamuk'un kitapları

Örnek 3: Sayfalama (Pagination)

Büyük veri setlerini parçalara bölme:

GET https://api.example.com/haberler?sayfa=2&adet=20

Örnek 4: Sıralama

Sonuçları belirli bir düzende getirme:

GET https://api.example.com/urunler?siralama=fiyat&yon=azalan

Yanıt: Fiyata göre azalan sırada ürünler

Örnek 5: Tarih Aralığı

Belirli tarihler arasındaki verileri getirme:

GET https://api.example.com/siparisler?baslangic=2024-01-01&bitis=2024-01-31

Yanıt: Ocak 2024 siparişleri

JSONPlaceholder ile Pratik

JSONPlaceholder, query string desteği sunan ücretsiz bir test API'sidir.

Tüm Postları Getir

GET https://jsonplaceholder.typicode.com/posts

Yanıt: 100 post

Belirli Kullanıcının Postları

GET https://jsonplaceholder.typicode.com/posts?userId=1

Yanıt: Sadece 1 numaralı kullanıcının postları (10 post)

Birden Fazla Filtre

GET https://jsonplaceholder.typicode.com/comments?postId=1&email=Eliseo@gardner.biz

Yanıt: 1 numaralı posta ait ve belirtilen emaile sahip yorumlar

TV Maze API Örneği

TV Maze API, query string ile güçlü arama özelliği sunar.

Dizi Arama

GET https://api.tvmaze.com/search/shows?q=game+of+thrones

Program Takvimi

Belirli bir ülke ve tarihteki TV programlarını getirme:

GET https://api.tvmaze.com/schedule?country=TR&date=2024-06-15

Query String vs URL Yolu

İkisi de veri taşır ama amaçları farklıdır:

URL Yolu (Path)

Belirli bir kaynağı tanımlar:

/kullanicilar/42        → 42 numaralı kullanıcı
/urunler/laptop-x500    → Laptop X500 ürünü
/kategoriler/elektronik → Elektronik kategorisi

Query String

Kaynağı filtreler, sıralar veya değiştirir:

/kullanicilar?aktif=true        → Aktif kullanıcılar
/urunler?siralama=fiyat         → Fiyata göre sıralı ürünler
/kategoriler?limit=5            → İlk 5 kategori

Ne Zaman Hangisi?

Hoppscotch'ta Query String

Yöntem 1: URL'e Doğrudan Yazma

https://api.tvmaze.com/search/shows?q=friends

Tüm string'i URL kutusuna yapıştırın.

Yöntem 2: Parameters Sekmesi

Daha düzenli ve hata yapmaya daha az açık:

1. Parameters sekmesine tıklayın
2. Anahtar-değer çiftlerini ekleyin:

Avantajları:

• Otomatik URL encoding
• Parametreleri açıp kapatabilme (checkbox)
• Daha okunaklı
• Hata yapma olasılığı düşük

Önemli Noktalar

1. Her API Farklı Parametreler Bekler

Bir API q beklerken, diğeri query veya search bekleyebilir:

Google:    ?q=arama
Twitter:   ?query=arama
GitHub:    ?q=arama
Spotify:   ?q=arama

Mutlaka dokümantasyonu okuyun!

2. Bilinmeyen Parametreler Genellikle Göz Ardı Edilir

GET https://jsonplaceholder.typicode.com/posts?rastgele=deger&sacma=123

API, rastgele ve sacma parametrelerini tanımıyorsa basitçe görmezden gelir. Hata vermez ama istediğiniz filtreleme de yapılmaz.

3. Büyük/Küçük Harf Duyarlılığı

Çoğu API büyük/küçük harf duyarlıdır:

?Category=elektronik  → Çalışmayabilir
?category=elektronik  → Doğru

4. Boş Değerler

Boş değer göndermek genellikle o parametreyi yok saymak demektir:

?isim=&sehir=ankara  → isim filtresi uygulanmaz

Sık Kullanılan Parametre İsimleri

Özet

Sırada Ne Var?

Query string ile URL'e nasıl parametre ekleneceğini öğrendik.

Bir sonraki makalede HTTP Headers (başlıklar) konusunu inceleyeceğiz.