Basit Dille API ve FastAPI

API, programların birbirleriyle iletişim kurma yöntemidir. Biri ister, diğeri cevap verir. Bir pazar yeri örneği üzerinden bir isteğin nelerden oluştuğunu, JSON yanıtının nasıl okunduğunu ve Claude Code harici bir veri kaynağı bağladığında neleri kontrol etmeniz gerektiğini inceleyeceğiz. Sonunda FastAPI ile nerede karşılaşabileceğinizi kısaca açıklayacağız.

Basit Dille API Nedir

API (Application Programming Interface) bir programlama arayüzüdür. Hangi işlemlerin kullanılabildiğini ve bunlara nasıl başvurulacağını tanımlar. API yalnızca tek tek uygulamalarda değil, kütüphanelerde, işletim sisteminde ve tarayıcıda da bulunur. Bir program onun aracılığıyla başka bir programdan veya onun bir bölümünden bir şey yapmasını isteyebilir ve sonucu alabilir. Burada ağırlıklı olarak, bir adres üzerinden erişilen ağ API'lerinden bahsedeceğiz.

Bir restoran hayal edin. Müşteri olarak mutfağa gitmiyor ve aşçıya yemeği nasıl pişireceğini anlatmıyorsunuz - garsona menüden ne istediğinizi söylüyorsunuz, o da siparişi mutfağa iletip hazır yemeği size getiriyor. API bu garsondur. İstemci program onun aracılığıyla sipariş verir ve mutfak (başka bir program) bunu yerine getirir. İçeride her şeyin nasıl çalıştığını bilmeniz gerekmez - menüyü bilmeniz ve ne isteyebileceğinizi ve cevap olarak ne alacağınızı anlamanız yeterlidir.

Aslında API bir sözleşmedir: "Bana şu şekilde başvurabilirsiniz, karşılığında da şu sonucu döndüreceğim".

İngilizce kısa ve esprili bir video da var - "How API work". Bu, aynı fikri canlandıran bir görsel; konunun açıklaması değil. Gerekli her şey aşağıdaki metinde var.

Pazar Yeri Örneğinde İstek ve Yanıt

Bir tedarikçinin ürünleri kendi programından aktardığı bir pazar yeri hayal edin. Binlerce ürünü sitenin düğmeleriyle tek tek aktarmak zahmetli olduğundan pazar yeri programlı API işlemleri sunar. Örneğin, POST /products bir ürün ekler ve GET /reports bir rapor döndürür.

Mevcut bir işlemin adresine endpoint denir. İsteği anlamak için hem adrese hem de HTTP yöntemine bakılır. GET /products ve POST /products farklı işlemler yapabilir. GET genellikle okuma için, POST ise verileri işlenmek üzere göndermek için kullanılır.

Veriler çoğu zaman JSON biçiminde iletilir. Süslü parantezler bir nesnenin alanlarını bir araya getirir, dizeler tırnak içinde, nesne listesi ise köşeli parantez içinde yazılır:

{
  "name": "Masa lambası",
  "price": 15000,
  "count": 350
}

İstemci bir istek gönderir, sunucu bunu işler ve yanıt döndürür. Aşağıda tam bir HTTP paketi değil, alışverişin kısaltılmış bir şeması var:

POST /products
{ "name": "Masa lambası", "price": 15000, "count": 350 }

201 Created
{ "id": 4567, "status": "added" }

201 Created yanıtın durum kodudur, altındaki JSON ise sonucu taşıyan gövdedir. Gerçek bir API'de belgeler endpoint'i, yöntemi, zorunlu parametreleri, başlıkları, yanıtın biçimini ve olası hataları belirtir. Tam veri setiyle değil, tek bir test nesnesiyle başlamak daha güvenlidir.

Frontend, Backend ve Aralarındaki API

API yalnızca farklı uygulamaları birbirine bağlamaya yaramaz. Çoğu zaman tek bir uygulamanın kendisi iki programdan oluşur ve bunlar da birbiriyle API üzerinden konuşur.

Frontend, uygulamanın tarayıcıda sizin kullandığınız kısmıdır. Düğmeler, görseller, menüler, formlar ve sayfanın davranışı buna dahildir. Programlama mantığı genellikle JavaScript ile yazılır. Frontend karmaşık hesaplamaları kendisi de yapabilir, veri ya da hizmet tarafında bir işlem gerektiğinde sunucuya da başvurabilir.

Backend, uygulamanın sunucu tarafıdır. Ödemeleri işler, siparişleri kaydeder, erişimi kontrol eder, ürünleri arar. Geliştirme sırasında sunucu sizin bilgisayarınızda, yayından sonra ise bir barındırma hizmetinde çalışabilir. Kullanıcı, sayfayla birlikte backend'in kaynak kodunu almaz. Tarayıcıya yalnızca isteklere verilen yanıtlar gelir.

Peki nasıl konuşurlar? Yine API üzerinden. Backend endpoint'lerini yalnızca dış tedarikçilere değil, kendi frontend'ine de açar:

• sayfayı açtınız - frontend /products/list endpoint'ini çağırır, backend ürün listesini döndürür, frontend de bunları güzelce ekrana çizer;
• "satın al" düğmesine bastınız - frontend verileri /orders endpoint'ine gönderir, backend siparişi oluşturur.

Yani API üzerinden hem farklı uygulamalar hem de tek bir uygulamanın parçaları konuşabilir. Bu şemada tarayıcı isteği gönderir, backend verilerle çalışıp sonucu döndürür. Veritabanının tarayıcıdan doğrudan erişilebilir olması gerekmez.

Tarayıcıdan İstek

Yukarıda frontend'in backend'in "endpoint'ini çağırdığını" söyledik. Bunun kodda nasıl göründüğüne bakalım. Tarayıcıda bunun için yerleşik fetch işlevi var. Belirtilen adrese HTTP isteği gönderir ve yanıtı döndürür. Yanıtın gövdesi genellikle JSON olarak gelir ve .json() yöntemiyle bir nesneye ayrıştırılır.

Bir yerel ayarlar (locale) listesi alalım: dil ve bölgesel ayarların birleşimleri. Backend'in bu listeyi /locales adresinden verebildiğini, frontend'in ise onu göstermesi gerektiğini varsayalım. Örneğin sunucu şunu döndürüyor:

[
  { "code": "en-GB", "language": "English", "country": "United Kingdom" },
  { "code": "de-DE", "language": "Deutsch", "country": "Germany" }
]

Yanıt Nasıl Gelir

Aşağıdaki parça, sayfa işleyicisinin asenkron bir işlevi içinde çalışır. Verileri alır; tablonun ekrana basılması burada gösterilmiyor.

const res = await fetch("/locales");
if (!res.ok) {
  throw new Error(`HTTP ${res.status}`);
}
const locales = await res.json();
// Artık locales tablo için gereken verileri içeriyor

Verileri okumadan önce res.ok değerini kontrol ediyoruz. 404 veya 500 gibi bir HTTP hatası, tek başına fetch'in istisnayla sonlanmasına yol açmaz. Bundan ayrı olarak ağ isteğinin kendisi gerçekleşmeyebilir ya da JSON ayrıştırılamayabilir. Böyle bir parçadan çıkan hatayı sayfanın kodu yakalamalı ve anlaşılır bir mesaj göstermelidir. Bunlar farklı nedenlerdir, ancak her durumda kullanıcı verileri alamamış olur. Ayrıntılar MDN'in fetch kılavuzunda.

Burada kolayca gözden kaçabilecek birkaç küçük ayrıntı var:

• fetch varsayılan olarak GET yapar, yani veri almaya yönelik bir istek gönderir. Diğer işlemler yöntemle belirtilir; örneğin bizim pazar yerimiz yeni ürünü POST ile kabul ediyor;
• /locales adresi görelidir. Normal bir HTTP sayfasında aynı origin'in köküne gider. Origin şema, host ve port ile belirlenir; sunucuda böyle bir rota bulunmalıdır;
• fetch ve .json() sonucu hemen döndürmez, bu yüzden önlerine await yazılır - "yanıtı bekle".

HTML'yi file:// üzerinden dosya olarak açarsanız, /locales yazısı HTTP sunucunuzun adresine dönüşmez. Bu örnekte sayfa, rotanın gerçekleştirildiği bir sunucu üzerinden açılır. HTML dosyasının kendisi böyle bir rota oluşturmaz.

Frontend ve API farklı origin'lerde bulunabilir. O zaman yanıtın tarayıcıdan okunabilmesi için API sunucusu gereken erişime CORS ile izin vermelidir. CORS, her ağ hatasının adı değil, siteler arası erişim mekanizmasıdır. Sayfayı ve API'yi aynı origin'de barındırmak örneği basitleştirir, ancak her uygulama için şart değildir. Ayrıntılar MDN'deki CORS açıklamasında.

Tarayıcıya Kim Yanıt Verir

fetch("/locales") isteğine kim yanıt verir? Backend, ve onun Python ile FastAPI üzerinde olması gerekmez. API belirli bir dil değil, programlar arasındaki bir anlaşmadır. Aynı endpoint Node.js, Go veya Java ile de yazılır. Örneğin bir Node.js sunucusunun işleyicisinde önceden hazırlanmış locales dizisini döndürebilirsiniz. Aşağıda hazır bir sunucu değil, işleyiciden yalnızca bir parça var:

// req ve res işleyiciye gelmiştir, locales önceden hazırlanmıştır
if (req.method === "GET" && req.url === "/locales") {
  res.statusCode = 200;
  res.setHeader("Content-Type", "application/json; charset=utf-8");
  res.end(JSON.stringify(locales));
}

Dışarıdan bakınca bu yine aynı GET /locales HTTP isteği, yanıtta da 200 durumu ve JSON var. Frontend'in backend'in neyle yazıldığını bilmesine gerek yok. Ona adres, istek kuralları ve yanıtın biçimi lazım.

API Türleri

API'leri iki ölçüte göre ayırmak işe yarar:

• yerel ve ağ API'leri - örneğin bir kütüphanenin API'si programın kodundan çağrılır, ağ API'sine ise ağ üzerinden başvurulur. Ağ, açık internet olmadan, dahili bir ağ da olabilir;
• herkese açık ve dahili API'ler - herkese açık olanlar dış geliştiriciler için tasarlanır, dahili olanlar sistemin parçalarını birbirine bağlar. Herkese açık bir API de kayıt, ödeme ve izin isteyebilir.

Web API'leri çoğunlukla istek ve yanıt protokolü olan HTTP'yi kullanır. Belgelerde karşınıza çıkacak REST ise API tasarlamaya yönelik bir yaklaşımı tanımlar; her HTTP API kendiliğinden REST'e uygun değildir. Şimdilik yanıttaki durum kodunu okumayı öğrenmek daha faydalı:

• 200 - her şey yolunda;
• 201 - oluşturuldu (örneğin POST sonrası yeni nesne);
• 404 - bulunamadı;
• 401 - istek uygun kimlik doğrulama bilgisi içermiyor;
• 429 - çok fazla istek;
• 500 - sunucunun iç hatası.

Şu an bunun derinine inmeniz gerekmiyor. Önemli olan, istek ve yanıt alışverişinin ana fikrini kavramak. Şimdilik bu kadarı yeterli.

Hizmet Neden Erişim Anahtarı İster

Birçok hizmet önce bir API anahtarı almanızı ister: hesabınıza veya projenize bağlı bir dize. Anahtar, belgelerde belirtilen şekilde, çoğu zaman isteğin başlığında iletilir. Hizmet erişimi kontrol eder ve kaç istek yaptığınızı sayabilir. Başka entegrasyonlarda token kelimesiyle karşılaşırsınız. Amacı benzerdir, ancak nasıl alındığı, geçerlilik süresi ve verdiği yetkiler farklı olabilir.

Uygun erişim olmadan istek gerçekleşmez; örneğin sunucu 401 ile yanıt verebilir. İstek sıklığının aşılması çoğu zaman 429 koduyla bildirilir. Yanıtın tam anlamına ve izin verilen hacimlere ilgili hizmetin belgelerinden bakılır. Hiç anahtar gerektirmeyen açık kaynaklar da var.

Hazır API Nerede Aranır

API'ler sayesinde uygulamalara haritalar, hava durumu, ödeme ve teslimat eklenir. Açık belgeler, hizmetin neler yapabildiğini daha bağlamadan anlamaya yardımcı olur. İşe görevin kendisinden başlamak daha iyidir. Hangi verilere ihtiyacınız olduğunu, ne sıklıkla güncellenmeleri gerektiğini ve onlarla ne yapmayı planladığınızı belirleyin.

Arama için API'lerin ve istek örneklerinin kataloğu olan Postman Public API Network'e bakmak işe yarar. Bulunan örnek yalnızca bir başlangıç noktasıdır. Adresi, biçimi, erişimi ve sınırlamaları yine de hizmet sahibinin resmi belgeleriyle karşılaştırın.

FastAPI Bunun Neresinde

FastAPI, Python'da API ve web sunucuları oluşturmaya yarayan framework'lerden biridir. Bir endpoint'i sunucu kodunuza bağlayabilir, isteği alıp JSON yanıtı döndürebilir. FastAPI, kendi Python backend'inizi oluşturduğunuzda gerekir; hazır bir API'yi kullanmak için onu öğrenmeniz gerekmez. 7. seviyede adını tanımanız ve bu sınırı anlamanız yeterli.

Claude Code ile Birlikte Nasıl Çalışır

Bu kavramlarla ajanın işini değerlendirmek daha kolay. Ajan başka birinin API belgelerini okuyabilir, istemci tarafı isteği yazabilir ya da sizin API'nizi FastAPI ile oluşturabilir. Sizin için önemli olan, istekten sayfadaki verilere uzanan somut yolu görmek. İsteği kim gönderiyor, kim yanıt veriyor ve yanıt nasıl işleniyor?

Örneğin bir deprem radarı için USGS'nin herkese açık GeoJSON feed'i var. Son bir saatin listesinin adresi:

GET https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson

Aşağıda yanıtın yapısını gösteren küçük bir eğitim örneği var; olay hayali, alanlar kısaltılmış. Bunlar güncel USGS verileri değildir:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "mag": 4.2, "place": "Eğitim noktası" },
      "geometry": { "type": "Point", "coordinates": [-122.5, 38.0, 8.0] }
    }
  ]
}

features içinde olayların dizisi bulunur. features[0].properties.mag yolu ilk olayın büyüklüğüne götürür. 0 indeksi dizinin ilk öğesi demektir. Koordinatlar "boylam, enlem, kilometre cinsinden derinlik" sırasıyla gelir. Ajan büyüklüğü noktanın boyutu, koordinatları da noktanın konumu için kullanabilir. Dizi boşsa ilk öğe yoktur; büyüklük null ise bu bilinmeyen bir değerdir, olayın sıfır şiddette olduğu anlamına gelmez.

Geriye istekten sonra ne gösterileceğine karar vermek kalıyor:

İstek sürerken sayfa bir yükleniyor göstergesi gösterebilir. Farklı sonuçları denemek için eğitim amaçlı yanıtlar kullanmak işe yarar. Böylece gerçek bir hizmet arızasını ya da yeni bir depremi beklemek gerekmez.

Claude Code'a verilecek görev artık şöyle olabilir:

Belirtilen API'deki verileri sayfaya bağla.
Önce resmi belgeleri kontrol et: adres, yöntem,
yanıt biçimi ve erişim koşulları. Hangi alanları kullandığını göster.
Yükleme, boş liste ve güncelleme hatası durumlarını hesaba kat.
Bir hatadan sonra eski verileri kullanırsan, bunu sayfada belirt.
Gizli anahtarı istemci koduna koyma.
Sonucu kontrol et ve hangi durumları doğrulayabildiğini bildir.

İş bittikten sonra yalnızca ortaya çıkan görüntüye değil, isteğin kendisine ve kontrolün sonucuna da bakın. Ajanın erişimini ve sayfanın erişimini ayrıca birbirinden ayırın. MCP Claude Code'a bir araç bağlayabilir, ancak yayınlanan uygulamanın kendi entegrasyonu olması gerekir. Sitenin istekleri uygulamanın kendisinde gerçekleştirildiyse, ajan oturumunun kapanması onları durdurmamalıdır.