API Nedir? REST API'yi Basitçe Anlamak

01API Nedir? Garson Benzetmesi

API nedir sorusunu anlatmanın en bilinen yolu restoran benzetmesidir. Siz müşterisiniz, mutfak ise veriyi tutan sistemdir. Mutfağa kendiniz giremezsiniz; menüye bakar, siparişi garsona verirsiniz. Garson isteği mutfağa iletir, hazır olan yemeği size getirir. Bu senaryoda garson API'dir.

Menü de API'nin belgesidir: neyi isteyebileceğinizi, nasıl isteyeceğinizi ve karşılığında ne alacağınızı söyler. Menüde olmayan bir şeyi isteyemezsiniz; mutfağın nasıl çalıştığını bilmek zorunda da değilsiniz.

Yazılım dünyasında bu düzen büyük bir kolaylık sağlar. Bir e-ticaret sitesinin kargo firmasının iç sistemini bilmesine gerek yoktur; kargo firmasının sunduğu API'ye “şu gönderi için etiket oluştur” der ve yanıtı alır. Her iki taraf da kendi iç yapısını değiştirebilir, yeter ki API sözleşmesi korunsun.

02API Ne İşe Yarar?

API ne işe yarar sorusunun yanıtı, günlük kullandığınız hemen her dijital hizmette saklıdır. Bir sitede haritadan konum seçmek, kartla ödeme yapmak, Google ile giriş yapmak ya da hava durumunu görmek, arka planda bir API çağrısıdır.

• Sistemleri birbirine bağlar: site, pazaryeri, kargo, muhasebe ve ödeme sistemleri tek akışta çalışır.
• Elle veri girişini azaltır: sipariş, stok ve fatura bilgisi bir sistemden diğerine kendiliğinden geçer.
• Mobil uygulamaları besler: telefondaki uygulama veriyi doğrudan veritabanından değil, API'den alır.
• Hazır hizmetleri kullanmayı sağlar: ödeme, harita, SMS ya da e-posta altyapısını sıfırdan yazmak gerekmez.
• Güvenli erişim sunar: dış tarafa veritabanının tamamı değil, yalnız izin verilen işlemler açılır.

03REST API Nedir?

API'ler farklı tarzlarda tasarlanabilir; web'de en yaygın olanı REST yaklaşımıdır. REST API nedir sorusunun kısa yanıtı: HTTP protokolünü kullanan, her veriyi bir adresle (kaynak) tanımlayan ve bu kaynaklar üzerinde standart metotlarla işlem yapan API tarzı.

REST'te her şey bir kaynaktır: ürünler, siparişler, müşteriler. Her kaynağın bir adresi vardır ve o adrese hangi HTTP metoduyla gittiğiniz, ne yapmak istediğinizi belirler. Yanıtlar çoğunlukla JSON biçiminde döner; hem insanın okuyabileceği hem de programların kolayca işleyebileceği bir metin formatıdır.

Endpoint Nedir?

Endpoint (uç nokta), API'de belirli bir işlemin yapıldığı adrestir. Örneğin /api/urunler ürün listesinin, /api/urunler/42 ise 42 numaralı ürünün uç noktasıdır. Bir API belgesi aslında bu uç noktaların, hangi metotla çağrıldıklarının ve ne döndürdüklerinin listesidir.

Durum Kodları

Her yanıtla birlikte bir HTTP durum kodu gelir ve işlemin sonucunu özetler. 200 başarılı, 201 kayıt oluşturuldu, 400 hatalı istek, 401 kimlik doğrulanmadı, 403 yetki yok, 404 bulunamadı, 429 çok fazla istek, 500 ise sunucu hatası anlamına gelir. İyi bir entegrasyon her kodu ayrı ele alır.

04Bir API İsteği Nasıl Görünür?

Bir API isteği temelde dört parçadan oluşur: adres, metot, başlıklar (kimlik bilgisi, veri türü) ve gerekiyorsa gövde (gönderilen veri). Aşağıda herkese açık bir deneme API'sine yapılan basit bir okuma isteği ve tipik bir JSON yanıtı görülüyor.

Bu isteği terminalden curl ile, tarayıcıdan JavaScript ile ya da sunucuda Python veya Node.js ile göndermek mümkündür; kurallar aynıdır, yalnız kullanılan araç değişir.

curl -s https://jsonplaceholder.typicode.com/posts/1 \
  -H "Accept: application/json"

{
  "userId": 1,
  "id": 1,
  "title": "...",
  "body": "..."
}

const yanit = await fetch("https://jsonplaceholder.typicode.com/posts/1");
if (!yanit.ok) throw new Error(`Hata: ${yanit.status}`);
const veri = await yanit.json();
console.log(veri.title);

05API Güvenliği ve Kimlik Doğrulama

Herkese açık deneme API'leri dışında, gerçek bir API'ye kim olduğunuzu kanıtlamadan erişemezsiniz. En yaygın yöntemler API anahtarı, kısa ömürlü erişim jetonları (token) ve OAuth gibi yetkilendirme akışlarıdır.

Güvenlik yalnız kimlik doğrulamadan ibaret değildir. İyi tasarlanmış bir API, her kullanıcıya yalnız gerektiği kadar yetki verir, gelen veriyi doğrular ve kötüye kullanımı önlemek için istek sayısını sınırlar (rate limit).

• API anahtarlarını asla tarayıcıya giden koda ya da herkese açık bir depoya koymayın.
• Bağlantıyı her zaman HTTPS üzerinden kurun.
• Anahtarları ortam değişkenlerinde saklayın ve düzenli aralıklarla yenileyin.
• Yalnız gereken izinleri isteyin; okuma yetkisi yetiyorsa yazma yetkisi almayın.
• Hata yanıtlarında iç sistem detaylarını dışarı sızdırmayın.

06API Entegrasyonu Örnekleri

API entegrasyonu, iki ya da daha fazla sistemin API'ler aracılığıyla düzenli ve otomatik veri alışverişi yapacak şekilde bağlanmasıdır. Bir e-ticaret işletmesinin günlük akışında bu bağlantıların neredeyse hepsi görülür.

Sipariş geldiğinde stok, ürünün satıldığı bütün kanallarda güncellenir; bu, pazaryeri entegrasyonu ile sağlanır. Sipariş onaylanınca kargo firmasından etiket ve takip numarası alınır; bu adım kargo entegrasyonu kapsamındadır. Fatura ise e-fatura entegrasyonu ile kendiliğinden kesilir ve müşteriye iletilir.

Bu bağlantıların hepsinde zor kısım ilk çağrıyı yapmak değildir. Karşı sistem yanıt vermediğinde ne olacağı, aynı siparişin iki kez işlenmesinin nasıl önleneceği, hata olduğunda kimin haberdar edileceği gibi soruların yanıtı, sağlam bir entegrasyon ile kırılgan bir bağlantı arasındaki farkı belirler.

API mi, Webhook mu?

API'de siz sorarsınız, karşı taraf yanıtlar. Webhook'ta ise karşı taraf, bir olay olduğunda size kendiliğinden haber verir. Sürekli “yeni sipariş var mı” diye sormak yerine, sipariş geldiğinde bildirim almak çoğu zaman daha verimlidir; ayrıntılar webhook nedir yazımızda.

07API Geliştirmeye Nereden Başlanır?

API kullanmayı öğrenmek için önce herkese açık bir deneme API'si seçip istekleri curl ya da bir API test aracıyla göndermek iyi bir başlangıçtır. Yanıtları okumak, durum kodlarını yorumlamak ve hata durumlarını denemek, kavramları hızla oturtur.

Kendi API'nizi yazmak istiyorsanız arka yüz dili seçmeniz gerekir. Hızlı ve okunaklı bir başlangıç için Python nedir yazımızdaki FastAPI örneğine, JavaScript ile ilerlemek istiyorsanız Node.js nedir yazısındaki Express örneğine bakabilirsiniz.

Her durumda iyi bir API'nin üç ortak özelliği vardır: net ve güncel belge, tutarlı adlandırma ve öngörülebilir hata yanıtları. Bir API'yi kullanacak geliştirici belgeyi okuyup ilk isteğini birkaç dakikada yapabiliyorsa, tasarım doğru yoldadır.