curl ile HTTP İstekleri ve API Testi

Bir web servisinin gerçekten çalışıp çalışmadığını anlamanın en hızlı yolu tarayıcı açmak değildir. Tarayıcı araya önbellek, çerez, eklenti ve otomatik yönlendirme sokar; siz sunucunun ne döndürdüğünü görmek isterken karşınıza tarayıcının yorumladığı hâli çıkar. Bir sistem yöneticisi ya da geliştirici bir sorunu çözerken ham gerçeği ister: Sunucu hangi durum kodunu döndü, hangi başlıkları gönderdi, gövdede tam olarak ne var? İşte curl tam olarak bunu yapar. Terminale yazdığınız tek satırlık bir komutla bir isteği elle kurar, gönderir ve yanıtı hiçbir katman araya girmeden önünüze serer.

Bu rehberde curl'ün günlük işlerde en çok kullanılan yeteneklerini pratik örneklerle ele alacağız. GET ve POST isteklerini, başlık göndermeyi, JSON gövdesi yollamayı, dosya indirmeyi, kimlik doğrulamayı, yönlendirme takibini ve en önemlisi HTTP durum kodlarını okumayı adım adım göreceğiz. Amaç curl'ü sadece bir "indirme aracı" olarak değil, API'lerinizi ve webhook'larınızı test edip sorun giderdiğiniz bir teşhis aleti olarak kullanabilmeniz. Örnekler gerçek senaryolara dayanır; olduğu gibi kopyalayıp kendi sunucunuzda deneyebilirsiniz.

curl Nedir ve Neden Terminal?#

curl (Client URL) 1998'den beri geliştirilen, neredeyse her Linux dağıtımında ve modern Windows sürümlerinde hazır gelen bir komut satırı aracıdır. HTTP, HTTPS, FTP, SMTP gibi onlarca protokolü konuşur ama pratikte en çok HTTP/HTTPS için kullanılır. Tek bir çalıştırılabilir dosyadan ibaret olması onu betiklere, cron görevlerine ve sunucu içi otomasyonlara mükemmel uyar; ekstra bir bağımlılık kurmadan bir sağlık kontrolü ya da webhook çağrısı yapabilirsiniz.

Terminalden istek atmanın somut avantajı tekrarlanabilirlik ve şeffaflıktır. Bir isteği bir kez doğru kurduğunuzda onu betiğe koyabilir, bir başkasına gönderebilir ya da altı ay sonra aynı şekilde çalıştırabilirsiniz. Kurulu olup olmadığını görmek için sürüm bilgisine bakalım.

curl --version

Çıktı curl 8.5.0 gibi bir sürümle başlar ve desteklenen protokolleri sıralar. Eğer komut bulunamazsa Ubuntu/Debian tarafında sudo apt install curl, RHEL/AlmaLinux tarafında sudo dnf install curl ile kurabilirsiniz. Temel Linux komutlarına aşina değilseniz Linux temel komutlar rehberimiz iyi bir başlangıç noktası olur.

Temel GET İstekleri#

curl'ün varsayılan davranışı bir GET isteği atıp yanıt gövdesini ekrana basmaktır. En sade kullanım budur.

curl https://clou.tr

Bu komut sayfanın HTML kaynağını olduğu gibi terminale döker. Çıktı çok uzunsa less ile sayfalayabilir ya da bir dosyaya yönlendirebilirsiniz. Ancak bir API'yi test ederken genellikle gövdenin yanında ne olup bittiğini de görmek istersiniz. Burada iki bayrak işinize yarar: -v (verbose) tüm el sıkışmayı, gönderilen ve alınan başlıkları gösterir; -s (silent) ise ilerleme çubuğunu bastırır.

curl -s https://api.clou.tr/v1/durum
curl -v https://api.clou.tr/v1/durum

-v çıktısında > ile başlayan satırlar sizin gönderdiğiniz, < ile başlayan satırlar sunucudan gelen verilerdir. Bu ayrım sorun giderirken paha biçilmezdir; bir başlığın gerçekten gidip gitmediğini ya da sunucunun hangi Content-Type ile cevap verdiğini tam olarak buradan okursunuz. Betiklerde çıktıyı sessize almak isterken hataların da kaybolmasını önlemek için -sS kullanmak yaygın bir alışkanlıktır; -s sessizleştirir, ilave -S yalnızca hata mesajlarını yine de gösterir.

Sorgu parametreleri göndermek için URL'yi tırnak içine almak önemlidir, çünkü & karakteri kabukta arka planda çalıştırma anlamına gelir.

curl -s "https://api.clou.tr/v1/urunler?kategori=hosting&sirala=fiyat"

Başlık Göndermek (-H)#

HTTP başlıkları isteğin meta verisini taşır: hangi biçimde cevap istediğinizi, kimlik bilgisini, istemci türünü. curl'de her başlık -H bayrağıyla eklenir ve bayrağı istediğiniz kadar tekrarlayabilirsiniz.

curl -s https://api.clou.tr/v1/hesap \
  -H "Accept: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn..." \
  -H "X-Client: curl-test"

Accept başlığı sunucuya JSON istediğinizi söyler; birçok API bu başlığa göre HTML mi yoksa JSON mı döneceğine karar verir. Authorization başlığı ise korumalı uç noktalarda kimliğinizi taşır. Clou.TR'nin API Gateway mimarisinde olduğu gibi JWT tabanlı sistemlerde token'ı tam olarak bu şekilde Bearer öneki ile gönderirsiniz. Uzun komutları okunur tutmak için satır sonuna ters bölü \ koyup bir sonraki satıra geçebilirsiniz.

Varsayılan User-Agent başlığını değiştirmek de sık ihtiyaç duyulan bir şeydir; bazı sunucular curl'ün varsayılan kimliğini engeller.

curl -s https://clou.tr -H "User-Agent: Mozilla/5.0 (uyumluluk-testi)"

POST ile Veri Gönderme ve JSON#

Bir kaynağı oluşturmak ya da güncellemek için POST kullanılır. curl'de gövde verisi göndermek -d (data) bayrağıyla olur ve -d kullandığınız anda curl yöntemi otomatik olarak POST'a çevirir; ayrıca -X POST yazmanıza gerek kalmaz. Klasik form verisi şöyle gider.

curl -s https://api.clou.tr/v1/giris \
  -d "[email protected]" \
  -d "sifre=GucluParola123"

Bu kullanımda curl Content-Type: application/x-www-form-urlencoded başlığını kendisi ekler. Ancak modern API'lerin büyük çoğunluğu JSON bekler. JSON gönderirken iki şeye dikkat edin: Doğru Content-Type başlığını elle vermek ve curl'ün gövdeye dokunmasını engellemek. -d bazı durumlarda satır sonlarını temizler; ham veriyi bozmadan yollamak için --data-raw daha güvenlidir.

curl -s https://api.clou.tr/v1/siparis \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  --data-raw '{"urun_id": 42, "adet": 1, "donem": "yillik"}'

Burada JSON'ı tek tırnak içine almak kritiktir; böylece içindeki çift tırnaklar kabuk tarafından yorumlanmaz. Token'ı $TOKEN gibi bir ortam değişkeninden okumak hem komutu temiz tutar hem de gizli anahtarın komut geçmişinde kalmasını önler. Yöntemi açıkça belirtmek istediğinizde -X kullanılır; DELETE ya da PUT gibi yöntemler için bu gereklidir.

curl -s -X DELETE https://api.clou.tr/v1/siparis/42 \
  -H "Authorization: Bearer $TOKEN"

Uzun ya da hassas gövdeleri komut satırına yazmak yerine bir dosyadan okutmak daha temizdir. @ öneki curl'e "bu bir dosya adı" der.

curl -s https://api.clou.tr/v1/siparis \
  -H "Content-Type: application/json" \
  --data-raw @siparis.json

Dosya İndirme#

curl'ün belki de en bilinen kullanımı dosya indirmedir. İki temel bayrak vardır ve aralarındaki fark sık karıştırılır. -o (küçük o) çıktıyı belirttiğiniz isimle kaydeder; -O (büyük O) ise URL'deki dosya adını korur.

curl -o yedek.tar.gz https://clou.tr/dosyalar/backup-2026.tar.gz
curl -O https://clou.tr/dosyalar/backup-2026.tar.gz

Büyük dosyalarda ya da kararsız bağlantılarda -L ve -C - birlikte hayat kurtarır. -L yönlendirmeleri takip eder (birazdan değineceğiz), -C - ise yarım kalmış indirmeyi kaldığı yerden sürdürür.

curl -L -C - -O https://clou.tr/dosyalar/buyuk-imaj.iso

Aşağıdaki tablo indirmede en çok kullanılan bayrakları özetler.

Bir yedekleme betiği yazıyorsanız bu bayrakları birleştirmek işinizi görür. Sunucu tarafındaki otomatik yedekleme ihtiyaçları için yedekleme hizmetimize de göz atabilirsiniz.

Yanıt Başlıklarını ve Durum Kodlarını İncelemek#

Bir API'yi test ederken çoğu zaman gövde değil, yanıtın "üst bilgisi" ilgilendirir sizi. -I (büyük i) yalnızca bir HEAD isteği atar ve sadece başlıkları getirir; sayfayı indirmeden sunucunun ne dediğini görürsünüz.

curl -I https://clou.tr

Çıktının ilk satırı en değerlisidir: HTTP/2 200 gibi durum kodunu verir. Hem başlıkları hem gövdeyi birlikte görmek isterseniz -i (küçük i) kullanın; bu HEAD değil normal GET atar ama yanıtın başına başlıkları da ekler.

HTTP durum kodları sunucunun ruh hâlidir; hangi ailede olduklarını bilmek sorunun kaynağını daraltır.

Betiklerde sadece durum kodunu değişkene almak çok işe yarar. -w (write-out) yanıt tamamlandıktan sonra istediğiniz ölçümleri basar; -o /dev/null ile gövdeyi çöpe atıp sadece kodu okuyabilirsiniz.

curl -s -o /dev/null -w "%{http_code}\n" https://clou.tr/panel

Aynı -w ile performans da ölçülür; bir uç noktanın ne kadar sürede cevap verdiğini görmek sorun giderirken altın değerindedir.

curl -s -o /dev/null \
  -w "kod: %{http_code}  toplam: %{time_total}s  baglanti: %{time_connect}s\n" \
  https://api.clou.tr/v1/durum

Kimlik Doğrulama ve Yönlendirme Takibi#

Temel kimlik doğrulama (HTTP Basic Auth) gerektiren uç noktalarda -u bayrağı kullanıcı adı ve parolayı otomatik olarak Authorization başlığına kodlar.

curl -u kullanici:parola https://api.clou.tr/v1/ozel

Parolayı komuta yazmamak için sadece kullanıcı adını verip curl'ün parolayı sizden gizlice istemesini sağlayabilirsiniz; -u kullanici yazıp Enter'a bastığınızda parola ekranda görünmeden sorulur. Token tabanlı sistemlerde ise -u yerine daha önce gördüğümüz -H "Authorization: Bearer ..." yöntemi tercih edilir.

Yönlendirmelere gelince: Bir adres 301 ya da 302 ile başka bir yere yönlendiriyorsa curl varsayılan olarak o yönlendirmeyi takip etmez, sadece 3xx yanıtını gösterir. -L bayrağı curl'e "yönlendirmeyi izle ve hedefe git" der.

curl -sIL http://clou.tr

Bu komut http üzerinden başlayıp muhtemelen https'e yapılan yönlendirmeyi izler ve zincirdeki her adımın başlıklarını sırayla gösterir; sitenizin http'den https'e doğru yönlendirmesinin çalışıp çalışmadığını test etmenin en temiz yoludur. Nginx tarafında bu yönlendirmeyi kurmak isterseniz Nginx kurulumu rehberimizde ayrıntılı örnekler var. Basit bir yönlendirme yapılandırması şuna benzer.

server {
    listen 80;
    server_name clou.tr www.clou.tr;
    return 301 https://$host$request_uri;
}

SSL sertifikası henüz kurulu değilse ve curl certificate problem hatası veriyorsa üretimde çözüm sertifikayı düzeltmektir; test ortamında geçici olarak -k ile doğrulamayı atlayabilirsiniz ama üretimde asla kullanmayın. Doğru sertifika için SSL sayfamıza bakabilirsiniz.

Webhook ve Uç Nokta Testi#

Webhook, bir olay gerçekleştiğinde bir sistemin başka bir adrese otomatik POST atmasıdır: Ödeme onaylandı, sunucu düştü, form gönderildi gibi. Webhook alıcınızın doğru çalışıp çalışmadığını, dış sistemin göndereceği isteği curl ile birebir taklit ederek test edersiniz. Örneğin bir izleme sisteminin göndereceği "sunucu kapandı" bildirimini şöyle simüle edebilirsiniz.

curl -s -X POST https://webhook.clou.tr/uptime \
  -H "Content-Type: application/json" \
  -H "X-Cloutr-Signature: sha256=abc123..." \
  -w "\nDurum: %{http_code}\n" \
  --data-raw '{"servis":"vds-12","durum":"down","zaman":"2026-07-10T09:15:00Z"}'

Buradaki imza başlığı önemlidir. Ciddi webhook sistemleri gövdeyi bir gizli anahtarla imzalar (HMAC) ve alıcı bu imzayı doğrular; böylece sahte istekler ayıklanır. Test ederken imzayı doğru üretmezseniz alıcı 401 ya da 403 dönebilir, bu beklenen bir davranıştır. Discord ya da Slack gibi platformlara webhook gönderiyorsanız gövde biçiminin o platformun beklediği şekilde olması gerekir; Slack {"text":"..."} bekler, Discord embed yapısı ister.

Bir uç noktanın canlı olup olmadığını periyodik denetlemek için curl'ü bir cron görevine ya da kısa bir betiğe koymak yaygındır. Aşağıdaki betik durum kodu 200 değilse hata döndürür ve otomasyonda kullanılabilir.

#!/usr/bin/env bash
kod=$(curl -s -o /dev/null -w "%{http_code}" https://clou.tr/panel)
if [ "$kod" != "200" ]; then
  echo "UYARI: panel yanit vermiyor (kod $kod)"
  exit 1
fi
echo "Panel saglikli (200)"

Bu yaklaşımı bir adım öteye taşıyıp kendi sunucularınızın kesintilerini otomatik izlemek isterseniz Clou.TR panelindeki uptime uyarıları özelliği tam olarak bu işi yapar; siz curl ile elle test ederken sistem arka planda aynı denetimleri sürekli yürütür. Yönetimini bize bırakmak isterseniz sunucu yönetimi hizmetimiz devreye girer.

Zaman Aşımı ve Güvenli Kullanım#

Betiklerde curl'ü zaman aşımı olmadan çalıştırmak tehlikelidir; yanıt vermeyen bir sunucu betiğinizi süresiz kilitleyebilir. İki bayrak bunu önler: --connect-timeout bağlantı kurma süresini, --max-time ise tüm işlemin toplam süresini sınırlar.

curl -s --connect-timeout 5 --max-time 15 \
  -o /dev/null -w "%{http_code}\n" \
  https://api.clou.tr/v1/durum

Ağ hataları ve geçici kesintiler için otomatik yeniden deneme de eklenebilir; --retry 3 başarısız isteği üç kez tekrar dener ve aralarında bekler.

Son olarak güvenlik açısından iki alışkanlık edinin. Birincisi, token ve parolaları komut satırına düz yazmayın; history dosyasında ve ps çıktısında görünürler. Bunun yerine ortam değişkeni ya da --data-raw @dosya kullanın. İkincisi, -k/--insecure bayrağını üretimde asla kullanmayın; sertifika doğrulamasını kapatmak ortadaki adam saldırılarına kapı aralar. Bu iki kurala uyduğunuzda curl güvenli ve güçlü bir teşhis aracı olarak kalır.

Sıkça Sorulan Sorular#

curl ile wget arasındaki fark nedir?#

İkisi de komut satırından veri indirir ama odakları farklıdır. curl tek bir isteği kurup yanıtı ekrana basmaya, API test etmeye ve veri göndermeye odaklıdır; POST, özel başlık ve JSON gövdesi konusunda çok esnektir. wget ise özyinelemeli indirme ve tüm siteyi çekme gibi toplu indirme işlerinde daha güçlüdür. API testi ve tek istek denetimi için curl, arka planda büyük indirmeler için wget genellikle daha uygundur.

JSON gönderirken neden hata alıyorum?#

En yaygın sebep eksik ya da yanlış Content-Type başlığıdır. curl -d ile veri gönderdiğinizde başlığı application/x-www-form-urlencoded yapar; API JSON beklerken bunu görürse gövdeyi anlamaz. Çözüm -H "Content-Type: application/json" başlığını elle eklemek ve JSON'ı tek tırnak içine alarak --data-raw ile göndermektir. Bir diğer sık hata JSON içindeki tırnakların kabuk tarafından yorumlanmasıdır; tek tırnak içine almak bunu önler.

HTTP durum kodunu bir betikte nasıl yakalarım?#

Bunun için -o /dev/null -w "%{http_code}" kalıbını kullanırsınız. -o /dev/null yanıt gövdesini çöpe atar, -w "%{http_code}" ise yalnızca durum kodunu ekrana yazar. Çıktıyı bir kabuk değişkenine atadığınızda örneğin kodun 200 olup olmadığını if bloğuyla kontrol edip sağlık denetimi yapabilirsiniz. Aynı -w ile %{time_total} gibi süre ölçümlerini de alabilirsiniz.

curl yönlendirmeleri neden takip etmiyor?#

curl varsayılan olarak güvenlik ve öngörülebilirlik nedeniyle yönlendirmeleri izlemez; bir adres 301 ya da 302 dönerse sadece o yanıtı gösterir. Hedefe kadar gitmesini istiyorsanız komuta -L bayrağını eklemeniz gerekir. http'den https'e yönlendirmenizi test etmek için curl -sIL http://siteniz.com komutu zincirdeki her adımı sırayla gösterdiği için idealdir.

SSL sertifikası hatası alırsam ne yapmalıyım?#

Bu hata genellikle sertifikanın süresi dolduğunda, eksik ara sertifika (chain) olduğunda ya da alan adıyla eşleşmediğinde çıkar. Doğru çözüm test amaçlı -k ile doğrulamayı kapatmak değil, sertifikayı düzeltmektir; -k ortadaki adam saldırısına açık bırakır ve üretimde kullanılmamalıdır. Sertifika zincirini kontrol edip eksikse tamamlamalı, Let's Encrypt gibi bir sağlayıcıdan geçerli bir sertifika kurmalısınız.

curl komutumu neden tırnak içine almalıyım?#

URL'de &, ?, boşluk gibi karakterler ve JSON gövdesindeki tırnaklar kabuk (bash) tarafından özel anlamlarla yorumlanır. Örneğin tırnaksız bir & komutu arka plana atar, süslü tırnaklar sorgu parametrelerini bölebilir. URL'yi çift tırnak, JSON gövdesini tek tırnak içine almak bu karakterlerin curl'e olduğu gibi geçmesini sağlar ve beklenmedik davranışları önler. Bu küçük alışkanlık pek çok "neden çalışmıyor" anını baştan engeller.

Kapanış#

curl, tek bir komutla bir web servisinin gerçek davranışını görmenizi sağlayan sade ama güçlü bir araçtır. GET ve POST istekleri atmayı, başlık ve JSON göndermeyi, dosya indirmeyi, kimlik doğrulamayı, yönlendirmeleri izlemeyi ve en önemlisi durum kodlarını okumayı öğrendiğinizde bir API'yi ya da webhook'u dakikalar içinde test edebilir, bir sorunun kaynağını hızla daraltabilirsiniz. Anahtar, bu bayrakları ezberlemek değil; her isteğin ne gönderip ne aldığını şeffafça görmenin verdiği güveni kazanmaktır.

Bu tür teşhisleri elle yapmak yerine altyapınızın izlenmesini ve yönetilmesini uzmanlara bırakmak isterseniz Clou.TR yanınızda. Yüksek performanslı sunucu ve VDS çözümlerimizden ölçeklenebilir hosting paketlerimize, SSL sertifikalarından proaktif sunucu yönetimi hizmetimize kadar tüm servislerimizle projelerinizin arkasındayız. Daha fazla teknik rehber için Linux temel komutlar ve diğer Bilgi Merkezi makalelerimize göz atabilir, ihtiyacınıza uygun paketi seçmek için ekibimizle iletişime geçebilirsiniz.