REST API Nedir: Temel Kavramlar ve HTTP Metodları

Tarafındankomut
0 Comments

Sistem yöneticisi olarak çalışırken er ya da geç bir REST API ile uğraşmak zorunda kalırsın. İster bir monitoring sistemi kuruyor ol, ister iki servis arasında veri aktarımı yapıyor ol, isterse bir bulut sağlayıcısının kaynaklarını yönetiyor ol; REST API artık modern altyapının vazgeçilmez bir parçası. Bu yazıda REST API’nin temel kavramlarını, HTTP metodlarını ve bunları günlük sysadmin işlerinde nasıl kullanacağını ele alacağız.

REST API Nedir

REST, Representational State Transfer kelimelerinin kısaltmasıdır. 2000 yılında Roy Fielding’in doktora tezinde tanımladığı bir mimari stildir. REST bir protokol değil, bir tasarım felsefesidir. HTTP üzerinde çalışır ve belirli kural setlerine uyulduğunda sistemler arasında oldukça temiz ve tutarlı bir iletişim sağlar.

API ise Application Programming Interface demek. İki yazılımın birbiriyle nasıl konuşacağını tanımlayan sözleşmedir. REST API dediğimizde, REST mimarisini kullanan bir HTTP tabanlı arayüzden bahsediyoruz.

Sysadmin gözüyle bakarsak, REST API şu anlama geliyor: Bir sunucuya HTTP isteği gönderiyorsun, sunucu sana JSON veya XML formatında cevap veriyor. Bu cevabı script’inde kullanıyorsun, log’a yazıyorsun, başka bir servise iletiyorsun. Hepsi bu kadar.

REST’in Temel İlkeleri

REST mimarisinin birkaç temel kuralı var. Bunları bilmek, bir API’nin nasıl davranacağını tahmin etmeni sağlar:

  • Client-Server Ayrımı: İstemci ve sunucu birbirinden bağımsızdır. Sunucu sadece veri sağlar, nasıl gösterileceğiyle ilgilenmez.
  • Stateless (Durumsuz): Her istek kendi içinde tüm bilgiyi taşır. Sunucu önceki istekleri hatırlamaz. Bu yüzden her istekte authentication bilgilerini göndermek zorundasın.
  • Cacheable: Yanıtlar önbelleğe alınabilir olmalıdır. Bu performansı artırır.
  • Uniform Interface: Tüm kaynaklar aynı standart arayüz üzerinden erişilebilir olmalıdır.
  • Layered System: İstemci, arada kaç katman olduğunu bilmek zorunda değildir. Load balancer, proxy, CDN; bunların hepsi şeffaf çalışabilir.

HTTP Metodları: REST’in Dili

REST API’lerin temel yapı taşları HTTP metodlarıdır. CRUD operasyonları ile doğrudan ilişki kurulabilir:

  • GET: Veri okuma (Read)
  • POST: Yeni kayıt oluşturma (Create)
  • PUT: Kaydı tamamen güncelleme (Update)
  • PATCH: Kaydı kısmen güncelleme (Partial Update)
  • DELETE: Kayıt silme (Delete)

Bunların dışında daha az kullanılan ama bilmen gereken metodlar da var:

  • HEAD: GET gibi çalışır ama sadece header döner, body gelmez. Dosya varlığını kontrol etmek için idealdir.
  • OPTIONS: Sunucunun hangi metodları desteklediğini öğrenmek için kullanılır. CORS mekanizmasının temelinde bu vardır.

GET Metodu

GET, bir kaynaktan veri almak için kullanılır. Idempotent’tir, yani kaç kez çağırırsan çağır sonuç aynıdır ve sunucuda hiçbir şey değişmez. Sunucunun güvenlik gruplarını listelemek için bir örnek:

# Temel GET isteği
curl -X GET https://api.example.com/servers 
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." 
  -H "Content-Type: application/json"

# Query parameter ile filtreleme
curl -X GET "https://api.example.com/servers?status=running&region=eu-west-1" 
  -H "Authorization: Bearer TOKEN_BURAYA"

Query parameter’lar URL’e ?anahtar=değer formatında eklenir ve birden fazlası & ile birleştirilir. Monitoring sistemlerinde belirli bir zaman aralığındaki metrikleri çekmek için bu yapıyı sık kullanırsın.

POST Metodu

POST, sunucuda yeni bir kaynak oluşturmak için kullanılır. İdempotent değildir; aynı isteği iki kez gönderirsen iki farklı kayıt oluşabilir. Bunu aklında tutmak önemli.

# Yeni sunucu oluşturma
curl -X POST https://api.example.com/servers 
  -H "Authorization: Bearer TOKEN_BURAYA" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "web-prod-03",
    "region": "eu-west-1",
    "size": "s-2vcpu-4gb",
    "image": "ubuntu-22-04-x64",
    "tags": ["production", "web"]
  }'

Gerçek dünyada bunu ne zaman kullanırsın? Ansible playbook yerine doğrudan API çağrısıyla droplet oluşturmak, Slack’e alert göndermek, Jira’da otomatik ticket açmak gibi durumlar sayılabilir.

PUT ve PATCH Metodları

Bu ikisinin farkını anlamak önemli. PUT, kaynağın tamamını değiştirir. Göndermediğin alanlar silinir ya da varsayılan değere döner. PATCH ise sadece gönderdiğin alanları günceller, gerisine dokunmaz.

# PUT ile sunucu bilgisini tamamen güncelle
curl -X PUT https://api.example.com/servers/12345 
  -H "Authorization: Bearer TOKEN_BURAYA" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "web-prod-03-updated",
    "region": "eu-west-1",
    "size": "s-4vcpu-8gb",
    "image": "ubuntu-22-04-x64",
    "tags": ["production", "web", "updated"]
  }'

# PATCH ile sadece tag güncelle
curl -X PATCH https://api.example.com/servers/12345 
  -H "Authorization: Bearer TOKEN_BURAYA" 
  -H "Content-Type: application/json" 
  -d '{
    "tags": ["production", "web", "v2"]
  }'

Pratik ipucu: Eğer API dokümantasyonu yoksa ve ikisi arasında kararsız kaldıysan PATCH kullanmak genellikle daha güvenlidir. En azından mevcut verilerini silme riskini azaltırsın.

DELETE Metodu

Kaynağı silmek için kullanılır. İdempotent olmalıdır; zaten silinmiş bir kaynağı silmeye çalışmak ya 404 ya da 204 döndürmelidir.

# Sunucu silme
curl -X DELETE https://api.example.com/servers/12345 
  -H "Authorization: Bearer TOKEN_BURAYA"

# Silme işlemini onaylı çalıştır ve durumu kontrol et
response=$(curl -s -o /dev/null -w "%{http_code}" 
  -X DELETE https://api.example.com/servers/12345 
  -H "Authorization: Bearer TOKEN_BURAYA")

if [ "$response" -eq 204 ] || [ "$response" -eq 200 ]; then
  echo "Sunucu basariyla silindi"
else
  echo "Silme basarisiz, HTTP kodu: $response"
fi

HTTP Durum Kodları

HTTP durum kodları, isteğin nasıl sonuçlandığını anlatan üç haneli sayılardır. REST API kullanırken bunları okumayı bilmek hayat kurtarır.

  • 2xx Başarılı:

– 200 OK: İstek başarılı, veri döndü – 201 Created: POST başarılı, yeni kaynak oluşturuldu – 204 No Content: Başarılı ama döndürülecek içerik yok (DELETE sonrası sık görülür)

  • 3xx Yönlendirme:

– 301 Moved Permanently: Kaynak kalıcı olarak taşındı – 304 Not Modified: Cache geçerli, yeni veri gönderilmedi

  • 4xx İstemci Hataları:

– 400 Bad Request: Gönderdiğin veri hatalı – 401 Unauthorized: Authentication gerekli ya da geçersiz – 403 Forbidden: Kimliğin doğru ama erişim izni yok – 404 Not Found: Kaynak bulunamadı – 429 Too Many Requests: Rate limit aşıldı

  • 5xx Sunucu Hataları:

– 500 Internal Server Error: Sunucuda bir şeyler ters gitti – 502 Bad Gateway: Gateway arkasındaki sunucu cevap vermedi – 503 Service Unavailable: Servis geçici olarak kullanılamıyor – 504 Gateway Timeout: Upstream sunucu zamanında yanıtlamadı

Gerçek Dünya Senaryosu: Sunucu Yönetimi Script’i

Şimdi bunların hepsini bir araya getirelim. Diyelim ki DigitalOcean API’sini kullanarak droplet yönetimi yapan bir bash script yazacaksın.

#!/bin/bash
# DO API ile basit sunucu yönetimi

DO_TOKEN="buraya_digitalocean_api_token"
API_URL="https://api.digitalocean.com/v2"

# Tüm droplet'ları listele
list_droplets() {
  echo "=== Mevcut Sunucular ==="
  curl -s -X GET "$API_URL/droplets" 
    -H "Authorization: Bearer $DO_TOKEN" 
    -H "Content-Type: application/json" | 
    python3 -c "
import sys, json
data = json.load(sys.stdin)
for d in data.get('droplets', []):
    print(f"ID: {d['id']} | Ad: {d['name']} | IP: {d['networks']['v4'][0]['ip_address'] if d['networks']['v4'] else 'N/A'} | Durum: {d['status']}")"
}

# Droplet sil
delete_droplet() {
  local droplet_id=$1
  echo "Droplet $droplet_id siliniyor..."
  
  http_code=$(curl -s -o /dev/null -w "%{http_code}" 
    -X DELETE "$API_URL/droplets/$droplet_id" 
    -H "Authorization: Bearer $DO_TOKEN")
  
  if [ "$http_code" -eq 204 ]; then
    echo "Basariyla silindi."
  else
    echo "Hata! HTTP kodu: $http_code"
  fi
}

# Çalıştır
list_droplets

Authentication ve Güvenlik Temelleri

REST API güvenliği bu yazı dizisinin ana konusu olduğundan burada temel kavramlara değineceğiz.

Bearer Token

En yaygın kullanılan yöntemdir. Token’ı Authorization header’ında gönderirsin:

curl -X GET https://api.example.com/resource 
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0"

API Key

Bazı API’ler token yerine API key kullanır. Bu key header’da, query parameter’da ya da request body’de olabilir:

# Header ile API key
curl -X GET https://api.example.com/resource 
  -H "X-API-Key: sk_live_abc123xyz789"

# Query parameter ile API key (tavsiye edilmez, loglanır)
curl -X GET "https://api.example.com/resource?api_key=sk_live_abc123xyz789"

Basic Authentication

Kullanıcı adı ve şifrenin Base64 ile encode edildiği yöntemdir. HTTPS olmadan asla kullanma:

# curl ile basic auth
curl -X GET https://api.example.com/resource 
  -u "kullanici:sifre"

# Veya manuel olarak
curl -X GET https://api.example.com/resource 
  -H "Authorization: Basic $(echo -n 'kullanici:sifre' | base64)"

Rate Limiting ile Başa Çıkmak

API’lerin büyük çoğunluğu rate limit uygular. Dakikada, saatte ya da günde belirli sayıda istek yapabilirsin. Bu limiti aştığında 429 Too Many Requests alırsın.

#!/bin/bash
# Rate limit aware API çağrısı

call_api_with_retry() {
  local url=$1
  local max_retries=3
  local retry=0
  
  while [ $retry -lt $max_retries ]; do
    response=$(curl -s -w "n%{http_code}" 
      -H "Authorization: Bearer $API_TOKEN" 
      "$url")
    
    http_code=$(echo "$response" | tail -1)
    body=$(echo "$response" | head -n -1)
    
    if [ "$http_code" -eq 200 ]; then
      echo "$body"
      return 0
    elif [ "$http_code" -eq 429 ]; then
      echo "Rate limit asildi. 60 saniye bekleniyor..." >&2
      sleep 60
      retry=$((retry + 1))
    elif [ "$http_code" -eq 500 ] || [ "$http_code" -eq 503 ]; then
      wait_time=$((2 ** retry * 5))
      echo "Sunucu hatasi ($http_code). $wait_time saniye bekleniyor..." >&2
      sleep $wait_time
      retry=$((retry + 1))
    else
      echo "Beklenmeyen hata: $http_code" >&2
      return 1
    fi
  done
  
  echo "Maksimum deneme sayisina ulasildi." >&2
  return 1
}

# Kullanım
call_api_with_retry "https://api.example.com/servers"

Bazı API’ler response header’larında rate limit bilgisini verir:

  • X-RateLimit-Limit: Toplam izin verilen istek sayısı
  • X-RateLimit-Remaining: Kalan istek hakkı
  • X-RateLimit-Reset: Limitin sıfırlanacağı Unix timestamp
# Rate limit bilgilerini header'dan oku
curl -I -X GET https://api.github.com/rate_limit 
  -H "Authorization: Bearer $GITHUB_TOKEN" 2>&1 | 
  grep -i "x-ratelimit"

curl’den Python’a Geçiş

Bash script’lerinde curl yeterli olsa da daha karmaşık senaryolarda Python’un requests kütüphanesi çok daha kullanışlıdır. Özellikle JSON işleme, hata yönetimi ve session yönetimi konularında:

# Python requests ile temel API çağrısı
python3 << 'EOF'
import requests
import json
import sys

API_URL = "https://api.example.com"
TOKEN = "buraya_token"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# GET isteği
response = requests.get(f"{API_URL}/servers", headers=headers, timeout=30)

if response.status_code == 200:
    servers = response.json()
    for server in servers.get("data", []):
        print(f"Sunucu: {server['name']} | IP: {server.get('ip', 'N/A')}")
elif response.status_code == 401:
    print("Authentication hatasi, token'i kontrol et", file=sys.stderr)
    sys.exit(1)
else:
    print(f"Beklenmeyen durum kodu: {response.status_code}", file=sys.stderr)
    sys.exit(1)
EOF

Webhook: API’nin Tersi

API’da sen sunucuya istek gönderirsin. Webhook’ta ise sunucu sana istek gönderir. Olaya dayalı (event-driven) entegrasyonlarda kullanılır.

Örneğin GitHub’da bir commit olduğunda, GitHub senin belirlediğin URL’e POST isteği atar. Sen bu isteği alır ve CI/CD pipeline’ını tetiklersin. Ya da bir e-ticaret sistemi ödeme tamamlandığında senin endpoint’ine bildirim gönderir.

# Basit webhook receiver (netcat ile test)
# Gerçek hayatta nginx + python/node kullanırsın

# Test amaçlı gelen webhook'u yakalamak için
nc -l -p 8080

# Ya da python ile
python3 -m http.server 8080

Webhook’ları güvenli hale getirmek için genellikle HMAC imzalama kullanılır. GitHub bunu X-Hub-Signature-256 header’ıyla yapar.

Sonuç

REST API artık sysadmin’lerin günlük işinin ayrılmaz bir parçası. Bulut sağlayıcılarının tamamı, modern monitoring araçlarının büyük kısmı, CI/CD sistemleri ve iletişim platformlarının hepsi REST API üzerinden yönetilebiliyor.

Bu yazıda ele aldığımız temel kavramları özetleyecek olursak; GET ile veri okuyorsun, POST ile yeni kaynak oluşturuyorsun, PUT/PATCH ile güncelliyorsun, DELETE ile siliyorsun. HTTP durum kodları sana ne olduğunu söylüyor. Authentication ile kimliğini kanıtlıyorsun. Rate limit’e takılırsan biraz bekliyorsun ve tekrar deniyorsun.

Curl ile başla, işler karmaşıklaştıkça Python’a geç. Script’lerinde her zaman hata kodlarını kontrol et ve uygun loglama yap. API token’larını asla kod içine gömmüyor olman lazım; environment variable ya da secrets manager kullan.

Bu seri devam edecek. Bir sonraki yazıda REST API güvenliğini derinlemesine ele alacağız: JWT token yapısı, OAuth 2.0 akışları, API gateway kullanımı ve güvenlik testleri. Takipte kal.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir