curl ile API İsteği Gönderme: GET, POST, PUT ve DELETE Metodları

Sistem yöneticiliğinde ve geliştirici dünyasında curl adeta bir İsviçre çakısı gibidir. Bir API’yi test etmek istiyorsunuz, bir servisin ayakta olup olmadığını kontrol etmeniz gerekiyor ya da otomasyon scriptleri yazıyorsunuz – bunların hepsinde curl karşınıza çıkacak. Bu yazıda curl’ü sadece basit GET istekleri göndermek için değil, gerçek API entegrasyonlarında kullanabileceğiniz seviyede ele alacağız.

curl Nedir ve Neden Bu Kadar Önemli?

curl (Client URL), komut satırından HTTP, HTTPS, FTP ve daha onlarca protokol üzerinden veri transferi yapmanızı sağlayan bir araçtır. Neredeyse her Linux/Unix sistemde varsayılan olarak kurulu gelir, Windows’ta da PowerShell ve modern sistemlerde kullanılabilir.

Bir sysadmin olarak curl bilmek size şu avantajları sağlar:

• Herhangi bir sunucuya SSH bağlantısı kurduğunuzda, tarayıcı veya GUI olmadan API testleri yapabilirsiniz
• Bash scriptlerine doğrudan API çağrıları entegre edebilirsiniz
• Ağ sorunlarını debug ederken HTTP seviyesinde ne olduğunu görebilirsiniz
• Postman veya benzeri araçlara erişiminiz olmadığı durumlarda işlerinizi halledebilirsiniz

Temel curl Parametreleri

Detaylı örneklere geçmeden önce sık kullanacağınız parametreleri tanıyalım:

• -X veya –request: HTTP metodunu belirtir (GET, POST, PUT, DELETE vb.)
• -H veya –header: İstek başlığı ekler
• -d veya –data: İstek gövdesini (body) gönderir
• -i veya –include: Yanıt başlıklarını çıktıya dahil eder
• -s veya –silent: İlerleme çubuğunu ve hata mesajlarını gizler
• -o veya –output: Yanıtı dosyaya yazar
• -L veya –location: Yönlendirmeleri takip eder
• -u veya –user: Kullanıcı adı ve şifre ile kimlik doğrulama yapar
• -k veya –insecure: SSL sertifika doğrulamasını atlar (dikkatli kullanın!)
• -v veya –verbose: Tüm istek/yanıt detaylarını gösterir
• –max-time: Maksimum bekleme süresini saniye cinsinden belirler
• -w veya –write-out: Tamamlanma sonrası özel format çıktısı sağlar

GET İstekleri

GET, bir kaynaktan veri okumak için kullanılan en temel HTTP metodudur. Sunucu tarafında hiçbir şeyi değiştirmemeli, sadece veri okumalısınız.

Basit GET İsteği

curl https://api.github.com/users/torvalds

Bu kadar basit. Ama çıktı okunaksız bir JSON yığını olacak. Bunu düzgün görmek için jq aracını kullanabilirsiniz:

curl -s https://api.github.com/users/torvalds | jq .

Header Bilgileriyle GET

Çoğu API, kimlik doğrulama için Authorization header’ı ister. Bir token ile istek gönderelim:

curl -s 
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." 
  -H "Accept: application/json" 
  -H "Content-Type: application/json" 
  https://api.ornekuygulama.com/v1/kullanicilar

Query Parameter ile GET

API’lerde filtreleme, sayfalama gibi işlemler için URL’e query parametresi eklersiniz. Burada URL’i tırnak içine almayı unutmayın, aksi halde shell & karakterini yanlış yorumlar:

curl -s "https://api.ornekuygulama.com/v1/siparisler?durum=aktif&sayfa=1&limit=20" 
  -H "Authorization: Bearer TOKEN_BURAYA"

Yanıt Kodunu Kontrol Etme

Otomasyon scriptlerinde HTTP yanıt kodunu kontrol etmek kritiktir:

HTTP_KODU=$(curl -s -o /dev/null -w "%{http_code}" https://api.ornekuygulama.com/saglik)

if [ "$HTTP_KODU" -eq 200 ]; then
  echo "API ayakta ve calisiyor"
elif [ "$HTTP_KODU" -eq 503 ]; then
  echo "KRITIK: API servisi kullanilamiyor!"
  # Burada alert gonderebilirsiniz
else
  echo "Beklenmeyen yanit kodu: $HTTP_KODU"
fi

Bu pattern’i monitoring scriptlerinde yoğun şekilde kullanıyorum. Cron job’a koyup her 5 dakikada bir çalıştırabilirsiniz.

POST İstekleri

POST, sunucu tarafında yeni bir kaynak oluşturmak için kullanılır. Form verisi ya da JSON body ile birlikte gönderilir.

JSON Body ile POST

Günümüz API’lerinin büyük çoğunluğu JSON formatını kullanır:

curl -s -X POST 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer TOKEN_BURAYA" 
  -d '{
    "isim": "Ahmet Yilmaz",
    "email": "[email protected]",
    "rol": "admin"
  }' 
  https://api.ornekuygulama.com/v1/kullanicilar

Değişkenlerle Dinamik POST

Gerçek dünya senaryolarında hardcoded değerler yerine değişkenler kullanırsınız:

#!/bin/bash

API_URL="https://api.ornekuygulama.com"
API_TOKEN="TOKEN_BURAYA"
KULLANICI_ADI="Mehmet Kaya"
KULLANICI_EMAIL="[email protected]"

YANIT=$(curl -s -X POST 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $API_TOKEN" 
  -d "{
    "isim": "$KULLANICI_ADI",
    "email": "$KULLANICI_EMAIL",
    "aktif": true
  }" 
  "$API_URL/v1/kullanicilar")

# Yaniti parse et
KULLANICI_ID=$(echo "$YANIT" | jq -r '.id')
DURUM=$(echo "$YANIT" | jq -r '.durum')

if [ "$DURUM" = "basarili" ]; then
  echo "Kullanici olusturuldu. ID: $KULLANICI_ID"
else
  echo "Hata: $YANIT"
  exit 1
fi

Form Data ile POST

Bazı eski API’ler veya authentication endpoint’leri form verisi ister. application/x-www-form-urlencoded formatında gönderim:

curl -s -X POST 
  -H "Content-Type: application/x-www-form-urlencoded" 
  -d "grant_type=password&username=admin&password=gizli_sifre&client_id=uygulama" 
  https://auth.ornekuygulama.com/oauth/token

Dosya Yükleme (Multipart POST)

Bir API’ye dosya göndermek için -F parametresini kullanırsınız:

curl -s -X POST 
  -H "Authorization: Bearer TOKEN_BURAYA" 
  -F "dosya=@/tmp/rapor.pdf" 
  -F "aciklama=Aylik sistem raporu" 
  -F "kategori=raporlar" 
  https://api.ornekuygulama.com/v1/dosyalar

@ işareti curl’e bunun bir dosya yolu olduğunu söyler.

PUT İstekleri

PUT, mevcut bir kaynağı tamamen güncellemek veya belirli bir ID ile yoksa oluşturmak için kullanılır. POST’tan farkı, genellikle kaynağın tamamını göndermeniz gerektiğidir (partial update için PATCH kullanılır).

Tam Kaynak Güncelleme

curl -s -X PUT 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer TOKEN_BURAYA" 
  -d '{
    "id": 42,
    "isim": "Ahmet Yilmaz",
    "email": "[email protected]",
    "rol": "super_admin",
    "aktif": true
  }' 
  https://api.ornekuygulama.com/v1/kullanicilar/42

PATCH ile Kısmi Güncelleme

Kaynağın sadece belirli alanlarını güncellemek istiyorsanız PATCH kullanın:

curl -s -X PATCH 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer TOKEN_BURAYA" 
  -d '{"aktif": false}' 
  https://api.ornekuygulama.com/v1/kullanicilar/42

Bu yaklaşım özellikle büyük nesnelerde çok daha verimlidir – tüm nesneyi göndermek yerine sadece değişen alanları gönderirsiniz.

DELETE İstekleri

DELETE, bir kaynağı kaldırmak için kullanılır. Geri dönüşü olmayan bir işlem olduğu için scriptlerde ekstra dikkat gerektirir.

Basit DELETE

curl -s -X DELETE 
  -H "Authorization: Bearer TOKEN_BURAYA" 
  https://api.ornekuygulama.com/v1/kullanicilar/42

Onaylı DELETE Script’i

Production ortamında toplu silme işlemi yapıyorsanız, onay mekanizması eklemek hayat kurtarır:

#!/bin/bash

KULLANICI_ID=$1
API_TOKEN="TOKEN_BURAYA"
API_URL="https://api.ornekuygulama.com"

if [ -z "$KULLANICI_ID" ]; then
  echo "Kullanim: $0 <kullanici_id>"
  exit 1
fi

# Once kullanicinin var olup olmadigini kontrol et
KULLANICI=$(curl -s 
  -H "Authorization: Bearer $API_TOKEN" 
  "$API_URL/v1/kullanicilar/$KULLANICI_ID")

KULLANICI_ISIM=$(echo "$KULLANICI" | jq -r '.isim')

if [ "$KULLANICI_ISIM" = "null" ]; then
  echo "Hata: $KULLANICI_ID ID'li kullanici bulunamadi"
  exit 1
fi

echo "Silinecek kullanici: $KULLANICI_ISIM (ID: $KULLANICI_ID)"
read -p "Devam etmek istiyor musunuz? (evet/hayir): " ONAY

if [ "$ONAY" != "evet" ]; then
  echo "Islem iptal edildi"
  exit 0
fi

HTTP_KODU=$(curl -s -o /dev/null -w "%{http_code}" 
  -X DELETE 
  -H "Authorization: Bearer $API_TOKEN" 
  "$API_URL/v1/kullanicilar/$KULLANICI_ID")

if [ "$HTTP_KODU" -eq 204 ] || [ "$HTTP_KODU" -eq 200 ]; then
  echo "Kullanici basariyla silindi"
else
  echo "Hata! HTTP Kodu: $HTTP_KODU"
  exit 1
fi

Gerçek Dünya Senaryoları

Senaryo 1: Slack’e Bildirim Gönderme

Monitoring sistemlerinde sık kullanılan bir pattern – bir olay gerçekleştiğinde Slack kanalına otomatik mesaj göndermek:

#!/bin/bash

SLACK_WEBHOOK_URL="https://hooks.slack.com/services/XXXXX/YYYYY/ZZZZZ"
SUNUCU_ADI=$(hostname)
MESAJ="*UYARI*: $SUNUCU_ADI uzerinde disk dolulugu %90'i gecti!"

curl -s -X POST 
  -H "Content-Type: application/json" 
  -d "{
    "text": "$MESAJ",
    "username": "SysAdmin Bot",
    "icon_emoji": ":warning:"
  }" 
  "$SLACK_WEBHOOK_URL"

echo "Slack bildirimi gonderildi"

Bu scripti cron’a ekleyip disk kullanımıyla birleştirebilirsiniz:

# Her saat basinda disk kontrolu yap
0 * * * * /usr/local/bin/disk_monitor.sh

Senaryo 2: JWT Token Alıp API Çağrısı Yapma

Çoğu modern API OAuth veya JWT tabanlı kimlik doğrulama kullanır. Önce token alıp sonra API çağrısı yapmak şöyle görünür:

#!/bin/bash

AUTH_URL="https://auth.ornekuygulama.com/oauth/token"
API_URL="https://api.ornekuygulama.com"
CLIENT_ID="uygulama_id"
CLIENT_SECRET="gizli_anahtar"

# Token al
TOKEN_YANIT=$(curl -s -X POST 
  -H "Content-Type: application/x-www-form-urlencoded" 
  -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET" 
  "$AUTH_URL")

ACCESS_TOKEN=$(echo "$TOKEN_YANIT" | jq -r '.access_token')

if [ "$ACCESS_TOKEN" = "null" ] || [ -z "$ACCESS_TOKEN" ]; then
  echo "Token alinamadi: $TOKEN_YANIT"
  exit 1
fi

echo "Token basariyla alindi"

# Token ile API cagrisi yap
KULLANICILAR=$(curl -s 
  -H "Authorization: Bearer $ACCESS_TOKEN" 
  -H "Accept: application/json" 
  "$API_URL/v1/kullanicilar?limit=100")

TOPLAM=$(echo "$KULLANICILAR" | jq '.toplam')
echo "Toplam kullanici sayisi: $TOPLAM"

Senaryo 3: Toplu İşlem – CSV’den API’ye Veri Aktarma

Bir CSV dosyasındaki verileri API aracılığıyla sisteme aktarmak:

#!/bin/bash

API_URL="https://api.ornekuygulama.com"
API_TOKEN="TOKEN_BURAYA"
CSV_DOSYASI="/tmp/kullanicilar.csv"
BASARILI=0
BASARISIZ=0

# CSV formatı: isim,email,departman
while IFS=',' read -r ISIM EMAIL DEPARTMAN; do
  # Baslik satirini atla
  [ "$ISIM" = "isim" ] && continue

  HTTP_YANIT=$(curl -s -X POST 
    -H "Content-Type: application/json" 
    -H "Authorization: Bearer $API_TOKEN" 
    -w "HTTP_KOD:%{http_code}" 
    -d "{
      "isim": "$ISIM",
      "email": "$EMAIL",
      "departman": "$DEPARTMAN"
    }" 
    "$API_URL/v1/kullanicilar")

  HTTP_KOD=$(echo "$HTTP_YANIT" | grep -o "HTTP_KOD:[0-9]*" | cut -d: -f2)

  if [ "$HTTP_KOD" -eq 201 ]; then
    echo "[OK] $EMAIL olusturuldu"
    ((BASARILI++))
  else
    echo "[HATA] $EMAIL - HTTP $HTTP_KOD"
    ((BASARISIZ++))
  fi

  # Rate limiting icin kisa bekleme
  sleep 0.1

done < "$CSV_DOSYASI"

echo "---"
echo "Tamamlandi: $BASARILI basarili, $BASARISIZ basarisiz"

Hata Ayıklama İpuçları

API ile çalışırken işler her zaman planlandığı gibi gitmez. İşte bu durumlarda kullandığım teknikler:

Verbose mod ile detaylı inceleme:

curl -v -X POST 
  -H "Content-Type: application/json" 
  -d '{"test": "veri"}' 
  https://api.ornekuygulama.com/v1/test 2>&1 | head -50

-v ile hem istek hem yanıt header’larını, TLS握 handshake bilgilerini görürsünüz. 2>&1 ile stderr ve stdout’u birleştirip pipe’layabilirsiniz.

SSL sorunlarını test etme:

# Gelistirme ortaminda sertifika dogrulamasini atla
curl -k -s https://dev-api.ornekuygulama.com/saglik

# Production'da KESINLIKLE -k kullanmayin!

Zaman aşımı ayarları:

curl --connect-timeout 5 
     --max-time 30 
     -s https://api.ornekuygulama.com/agir-islem

Proxy üzerinden istek:

curl -x http://proxy.sirket.com:8080 
  -H "Authorization: Bearer TOKEN" 
  https://dis-api.ornek.com/veri

curl ile API Response Cache Kontrolü

Bazı API’lerde cache header’larını kontrol etmek gerekir:

curl -s -I 
  -H "Authorization: Bearer TOKEN_BURAYA" 
  https://api.ornekuygulama.com/v1/raporlar/son

# -I sadece header'lari getirir, body gelmez
# Cache-Control, ETag, Last-Modified degerlerini gorebilirsiniz

Sonuç

curl, sysadmin araç kutusunun vazgeçilmez bir parçası. GET ile veri okuma, POST ile kaynak oluşturma, PUT/PATCH ile güncelleme ve DELETE ile silme işlemlerini komut satırından veya scriptlerden kolayca yapabilirsiniz.

Özellikle üzerinde durmak istediğim birkaç pratik nokta var: İlk olarak, production scriptlerinde her zaman HTTP yanıt kodunu kontrol edin – başarılı görünen bir istek aslında 4xx veya 5xx dönüyor olabilir. İkinci olarak, token ve şifre gibi hassas bilgileri script içine gömmek yerine environment variable veya secret management sistemleri kullanın. Üçüncü olarak, toplu işlemlerde rate limiting’e dikkat edin, API’yi boğmamak için kısa beklemeler ekleyin.

jq ile birlikte kullanıldığında curl inanılmaz derecede güçlü bir araca dönüşüyor. Eğer henüz jq öğrenmediyseniz, curl ile birlikte mutlaka öğrenmenizi tavsiye ederim – JSON API’lerle çalışmak çok daha keyifli hale geliyor.

Son olarak, -v parametresini debug sırasında, -s parametresini ise scriptlerde kullanma alışkanlığı edinin. Verbose çıktı sorunları çözerken paha biçilemezken, sessiz mod scriptlerde temiz çıktı almanızı sağlar. İyi API entegrasyonları!