API Nedir? REST API Temelleri ve Kullanımı

REST API kavramını anlamak, modern web geliştirmenin kapısını açan anahtardır. Önce genel tanımdan başlayalım: API (Application Programming Interface, Uygulama Programlama Arayüzü), iki yazılımın birbiriyle konuşmasını sağlayan kurallar bütünüdür. Hava durumu uygulamanız meteoroloji servisinden veriyi, e-ticaret sitesi ödeme sağlayıcısından onayı hep API'ler aracılığıyla alır. REST ise bu iletişimin web üzerinde nasıl tasarlanacağını tarif eden, Roy Fielding'in 2000 tarihli doktora tezinde tanımladığı mimari bir stildir.

REST API Nasıl Çalışır?

REST (Representational State Transfer), HTTP protokolünün üzerine kurulu birkaç basit prensibe dayanır:

• Her şey bir kaynaktır (resource) ve her kaynağın bir URL'si vardır: /users, /users/42, /users/42/orders gibi.
• Kaynak üzerinde yapılacak işlem, URL ile değil HTTP metodu ile belirtilir.
• İletişim durumsuzdur (stateless): her istek, sunucunun onu anlaması için gereken tüm bilgiyi kendisi taşır.
• Veri günümüzde neredeyse her zaman JSON formatında taşınır.

İstemci (tarayıcı, mobil uygulama veya başka bir sunucu) bir HTTP isteği gönderir; sunucu isteği işler ve bir status kodu ile birlikte yanıt döner. Bu kadar.

HTTP Metodları

REST API'lerde dört temel işlem (CRUD: Create, Read, Update, Delete) dört ana HTTP metoduna karşılık gelir:

• GET: Veri okur. GET /users/42 → 42 numaralı kullanıcıyı getirir. Sunucuda hiçbir şeyi değiştirmez.
• POST: Yeni kayıt oluşturur. POST /users → gövdedeki veriyle yeni kullanıcı yaratır.
• PUT / PATCH: Günceller. PUT kaynağın tamamını değiştirir, PATCH yalnızca gönderilen alanları günceller.
• DELETE: Siler. DELETE /users/42 → kullanıcıyı kaldırır.

İyi tasarlanmış bir API'de URL'ler isimlerden (/products), işlemler metodlardan oluşur; /getProducts veya /deleteUser gibi fiil içeren yollar REST tasarımına aykırı kabul edilir.

Status Kodları: Sunucunun Cevabı

Her HTTP yanıtı üç haneli bir status kodu taşır. Bilmeniz gereken en yaygın kodlar:

• 200 OK: İstek başarılı, yanıt gövdede.
• 201 Created: Yeni kaynak oluşturuldu (genellikle POST sonrası).
• 204 No Content: Başarılı ama dönecek gövde yok (genellikle DELETE sonrası).
• 400 Bad Request: İstek hatalı; eksik alan veya bozuk JSON olabilir.
• 401 Unauthorized: Kimlik doğrulanamadı; token eksik veya geçersiz.
• 403 Forbidden: Kimlik doğru ama bu kaynağa yetkiniz yok.
• 404 Not Found: Kaynak bulunamadı.
• 429 Too Many Requests: İstek limitini aştınız (rate limiting).
• 500 Internal Server Error: Sunucu tarafında hata.

Kaba kural: 2xx başarı, 4xx istemcinin hatası, 5xx sunucunun hatasıdır. Tüm kodların tam listesi için MDN'in HTTP status referansına bakabilirsiniz.

JSON: Ortak Dil

JSON (JavaScript Object Notation), API'lerin veri alışverişinde kullandığı hafif metin formatıdır. Anahtar-değer çiftlerinden ve dizilerden oluşur:

{
  "id": 42,
  "ad": "Ayşe Yılmaz",
  "aktif": true,
  "roller": ["editor", "yazar"],
  "adres": {
    "sehir": "Ankara",
    "ulke": "TR"
  }
}

JavaScript'te JSON.parse() metni nesneye, JSON.stringify() nesneyi metne çevirir; Python'da aynı işi json modülünün loads ve dumps fonksiyonları yapar.

Gerçek İstek Örnekleri: curl ve fetch

Komut satırından API test etmenin klasik aracı curl'dür. GitHub'ın halka açık API'sine bir GET isteği:

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

POST isteğiyle JSON gövde göndermek:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_ANAHTARINIZ" \
  -d '{"ad": "Ayşe", "email": "ayse@ornek.com"}'

Aynı isteklerin tarayıcı ve Node.js tarafındaki karşılığı fetch fonksiyonudur:

// GET isteği
const yanit = await fetch("https://api.github.com/users/octocat");
const kullanici = await yanit.json();
console.log(kullanici.public_repos);

// POST isteği
const cevap = await fetch("https://api.example.com/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.API_KEY}`,
  },
  body: JSON.stringify({ ad: "Ayşe", email: "ayse@ornek.com" }),
});

if (!cevap.ok) {
  throw new Error(`İstek başarısız: ${cevap.status}`);
}

Burada headers bölümü kritik rol oynar: Content-Type gönderdiğiniz verinin formatını, Authorization ise kimliğinizi sunucuya bildirir.

API Anahtarı Güvenliği

Çoğu API, kimlik doğrulama için size özel bir API anahtarı verir. Bu anahtar parola gibidir ve en sık yapılan hatalar şunlardır:

• Anahtarı doğrudan kod içine yazıp GitHub'a göndermek. Botlar halka açık depoları sürekli tarar; sızan anahtar dakikalar içinde kötüye kullanılabilir.
• Anahtarı frontend JavaScript koduna koymak. Tarayıcıya inen her şey kullanıcı tarafından okunabilir.

Unutmayın: Bir kez halka açılan anahtar, depo geçmişinden silinse bile ele geçirilmiş sayılır ve mutlaka yenilenmelidir.

İyi Bir API Tüketicisi Olmak

API kullanırken yalnızca istek atmayı değil, karşı tarafın kurallarına saygı göstermeyi de öğrenmelisiniz:

Pratik Yapma Zamanı

REST API öğrenmenin en hızlı yolu, halka açık bir API ile küçük bir uygulama yazmaktır. GitHub API, JSONPlaceholder gibi sahte veri servisleri veya halka açık hava durumu API'leri başlamak için idealdir. Önce curl ile uç noktaları keşfedin, sonra fetch ile aldığınız veriyi sayfada gösterin. HTTP'nin inceliklerini merak ettikçe MDN'in HTTP dokümantasyonu en güvenilir başvuru kaynağınız olacaktır.