API Nedir? Garson Benzetmesiyle

Bir uygulamada hava durumunu görüyorsun ama o uygulama havayı kendisi mi ölçüyor? Hayır; arkada bir garson çalışıyor: API.

Okuma süresi: 12–14 dakika Seviye: Başlangıç → Orta Konu: API, HTTP, JSON, REST

İçindekiler

1. API nedir?
2. Garson benzetmesi
3. Günlük hayattan örnekler
4. İstek ve cevap nasıl çalışır?
5. JSON nedir?
6. HTTP metotları: GET, POST, PUT, DELETE
7. Durum kodları: Garson ne cevap verdi?
8. Basit kod örneği
9. REST API nedir?
10. API anahtarı (API key)
11. Yeni başlayanların sık yaptığı hatalar
12. Sık sorulan sorular

1. API nedir?

API, Application Programming Interface kelimelerinin kısaltmasıdır; Türkçesi uygulama programlama arayüzü. Basitçe söylemek gerekirse API, iki yazılımın birbiriyle konuşmasını sağlayan kurallar bütünüdür.

Bir yazılım başka bir yazılımdan veri istemek ya da ona bir işlem yaptırmak istediğinde bunu API üzerinden yapar. İstek nasıl yazılacak, cevap hangi biçimde gelecek, hangi adrese gidilecek gibi her şey API ile belirlenir.

Kısacası API, yazılımlar arasındaki resmî iletişim kanalıdır.

2. Garson benzetmesi

Bir restorana gittiğini düşün:

• Sen masada oturan müşterisin. Yemek istiyorsun ama mutfağa girip kendi yemeğini yapman gerekmiyor.
• Mutfak, işi yapan yerdir. Malzemeler, aşçılar ve tarifler orada. Sen oraya doğrudan karışmazsın.
• Garson, seninle mutfak arasındaki aracıdır. Siparişini alır, mutfağa iletir, hazır olunca sana getirir.
• Menü, ne isteyebileceğini gösteren listedir. Menüde olmayan bir şeyi isteyemezsin.

İşte bunların yazılımdaki karşılıkları:

Müşteri mutfağın içini bilmek zorunda değildir. Aynı şekilde bir uygulama geliştiricisi de başka bir sistemin içinde ne olduğunu bilmeden onun API'sini kullanabilir.

3. Günlük hayattan örnekler

Farkında olmadan günde onlarca API kullanıyorsun:

• Hava durumu uygulaması: Verileri bir meteoroloji servisinin API'sinden çeker.
• Harita üzerinde konum: Bir uygulamada haritanın görünmesi genellikle bir harita API'si sayesindedir.
• "Google ile giriş yap" butonu: Site, kimlik doğrulama için Google'ın API'sini kullanır.
• Online ödeme: Alışveriş sitesi, ödeme kuruluşunun API'siyle konuşur.
• Döviz kuru gösteren siteler: Güncel kuru bir finans servisinden alır.
• Uçuş ve otel karşılaştırma siteleri: Birçok firmadan fiyatı API ile toplar.

Bu sayede herkes her şeyi sıfırdan yapmak zorunda kalmaz; hazır servisleri kullanır.

4. İstek ve cevap nasıl çalışır?

Bir API kullanımı genelde şu adımlardan oluşur:

1. İstemci bir istek (request) gönderir. Örneğin: "Bana İstanbul'un hava durumunu ver."
2. İstek internet üzerinden sunucuya gider. Hedef bir adrestir (URL), buna endpoint denir.
3. Sunucu isteği işler. Gerekirse veritabanına bakar, hesap yapar.
4. Sunucu cevap (response) gönderir. Cevap çoğunlukla JSON biçimindedir.
5. İstemci cevabı kullanıcıya gösterir. Örneğin ekranda "18°C, parçalı bulutlu" yazar.

Bu haberleşme çoğunlukla HTTP protokolü üzerinden yapılır; tıpkı tarayıcının bir web sayfasını açarken kullandığı protokol gibi.

5. JSON nedir?

API cevapları genellikle JSON (JavaScript Object Notation) biçiminde gelir. İnsanlar için okunması kolay, bilgisayarlar için işlenmesi kolay bir veri biçimidir.

{
  "sehir": "İstanbul",
  "sicaklik": 18,
  "durum": "Parçalı bulutlu",
  "ruzgar": {
    "hiz": 12,
    "yon": "Kuzey"
  }
}

Kurallar basittir: veriler anahtar: değer çiftleri hâlinde yazılır, süslü parantezler bir nesneyi, köşeli parantezler bir listeyi gösterir.

6. HTTP metotları: GET, POST, PUT, DELETE

Garsona "ne yapmak istediğini" söylemen gerekir. Sadece bakmak mı, yeni sipariş vermek mi, siparişi değiştirmek mi, iptal etmek mi? API'de bu HTTP metotlarıyla belirtilir:

Bu dörtlüye bazen CRUD (Create, Read, Update, Delete) denir ve uygulamaların yaptığı işlerin çoğunu özetler.

7. Durum kodları: Garson ne cevap verdi?

Sunucu cevap verirken bir durum kodu da gönderir. Bu kod, işin nasıl sonuçlandığını söyler:

Bir API ile çalışırken ilk bakacağın şeylerden biri budur. 4xx kodları genelde istemci tarafındaki, 5xx kodları sunucu tarafındaki sorundur.

8. Basit kod örneği

Aşağıdaki örnek, JSONPlaceholder adlı ve test amaçlı hazırlanmış ücretsiz bir sahte API'den bir yazı bilgisi çeker. (Bu, ders konusuyla uyumlu olarak bir dummy veri servisidir.)

JavaScript (tarayıcı konsolunda deneyebilirsin):

fetch("https://jsonplaceholder.typicode.com/posts/1")
  .then(cevap => cevap.json())
  .then(veri => {
    console.log(veri.title);
  })
  .catch(hata => console.log("Bir sorun oluştu:", hata));

Python:

# pip install requests
import requests

cevap = requests.get("https://jsonplaceholder.typicode.com/posts/1")
print(cevap.status_code)      # 200 gelmesini bekleriz
veri = cevap.json()
print(veri["title"])

Ne oldu? Kodun bir GET isteği gönderdi, sunucu JSON cevap verdi, sen de içinden title alanını yazdırdın. İşte API kullanmak bu kadar basit bir fikre dayanır.

9. REST API nedir?

Sık duyacağın bir terim: REST. REST, web API'lerinin nasıl düzenli tasarlanacağını anlatan bir yaklaşımdır. REST API'lerde adresler kaynakları temsil eder:

• GET /kullanicilar → tüm kullanıcıları getir
• GET /kullanicilar/5 → 5 numaralı kullanıcıyı getir
• POST /kullanicilar → yeni kullanıcı oluştur
• DELETE /kullanicilar/5 → 5 numaralı kullanıcıyı sil

Adres düzenli ve tahmin edilebilir olduğu için hem kullanması hem hatırlaması kolaydır.

10. API anahtarı (API key)

Birçok API herkese açık değildir. Restorandaki "rezervasyon" gibi, seni tanımak ister. Bunun için sana bir API anahtarı verir.

• Anahtar, istekte seni tanımlayan gizli bir koddur.
• Sunucu, kimin ne kadar kullandığını anahtarla takip eder.
• Çoğu ücretsiz API'de günlük/dakikalık istek sınırı (rate limit) vardır.

Önemli güvenlik kuralı: API anahtarını GitHub'a yükleme ve ön yüz kodunda herkesin görebileceği şekilde bırakma. Anahtarlar bir şifre gibi korunmalıdır; genellikle sunucu tarafında veya ortam değişkenlerinde saklanır.

11. Yeni başlayanların sık yaptığı hatalar

• Dokümantasyonu okumamak: Menüyü okumadan sipariş vermeye benzer. Hangi adresin, hangi bilgiyi beklediği orada yazar.
• Yanlış metot kullanmak: Veri göndermek için GET kullanmak gibi.
• Durum kodunu kontrol etmemek: Cevap gelmiş gibi görünür ama aslında hata olabilir.
• Anahtarı herkese açık yere koymak.
• Sınırı aşmak: Çok sık istek gönderirsen sunucu seni geçici olarak engelleyebilir.

12. Sık sorulan sorular

API sadece web için mi var?

Hayır. İşletim sistemlerinin, kütüphanelerin ve programlama dillerinin de API'si vardır. Ancak "API" denince çoğunlukla web API'leri kastedilir.

API ile veritabanı aynı şey mi?

Hayır. Veritabanı verinin saklandığı yerdir; API ise o veriye erişimin kontrollü kapısıdır. Garson mutfaktaki buzdolabına doğrudan erişim vermez, sen sadece istediğini söylersin.

Kendi API'mi yazabilir miyim?

Evet. Python (Flask, FastAPI), JavaScript (Node.js, Express), PHP ve birçok dilde API yazılabilir. Önce hazır API'leri kullanarak mantığı kavraman iyi bir başlangıçtır.

API ücretsiz mi?

Birçoğu belli bir kullanıma kadar ücretsizdir; fazlası için ücret isteyebilir. Kullanmadan önce şartları kontrol et.

Özet

Kendini dene

• Tarayıcı konsoluna fetch örneğini yapıştırıp çalıştır.
• JSON cevaptaki başka bir alanı (body) yazdır.
• Yanlış bir adres dene ve 404 hatasını gözlemle.
• Python ile requests örneğini çalıştır.
• Kendi günlük hayatından bir API örneği bul ve garson benzetmesiyle anlat.

Son söz: API, yazılım dünyasının garsonudur: sen ne istediğini söylersin, o mutfağa gider ve sonucu getirir. Bu fikri kavradığında modern uygulamaların nasıl birbirine bağlandığını çok daha kolay anlarsın.

Bu yazı eğitim amaçlıdır. Ayrıntılar sürüme ve işletim sistemine göre farklılık gösterebilir.