API Nedir? REST, JSON, HTTP Yöntemleri ve API Anahtarı Güvenliği: Yeni Başlayanlar İçin Rehber

API (Application Programming Interface, Uygulama Programlama Arayüzü), iki yazılımın birbiriyle belirli kurallar çerçevesinde konuşmasını sağlayan bir sözleşmedir. Hava durumu uygulamanızın güncel sıcaklığı nereden aldığını, bir e-ticaret sitesinin ödeme sayfasının bankayla nasıl konuştuğunu veya bir harita eklentisinin konum bilgisini nasıl çektiğini düşünün: hepsinde API vardır. Web geliştirmede en yaygın API biçimi HTTP üzerinden çalışan REST API'lerdir.

Restoran benzetmesi

API'yi restoranın garsonu gibi düşünün: siz (istemci) mutfağa (sunucu) doğrudan girmezsiniz; menüdeki seçenekleri garsona söylersiniz, garson siparişi mutfağa iletir ve yemeği getirir. Menü, API'nin sunduğu işlemlerin listesi; garson ise isteği ileten arayüzdür.

REST nedir?

REST (Representational State Transfer), web servislerinin tasarımı için bir mimari yaklaşımdır. Temel fikirler:

Kaynaklar: Her şey bir "kaynak"tır (kullanıcı, sipariş, ürün) ve bir URL ile tanımlanır: /kullanicilar/42.
HTTP yöntemleri: Kaynak üzerinde ne yapılacağını yöntem belirler.
Durumsuzluk (stateless): Sunucu, istekler arasında istemci durumunu saklamaz; her istek gerekli tüm bilgiyi içerir.
Standart biçimler: Veri genellikle JSON olarak taşınır.

HTTP yöntemleri

Yöntem	Amaç	Örnek
GET	Veri okuma (güvenli, veriyi değiştirmez)	`GET /kullanicilar/42`
POST	Yeni kaynak oluşturma veya işlem başlatma	`POST /siparisler`
PUT	Bir kaynağı tamamen değiştirme/oluşturma	`PUT /kullanicilar/42`
PATCH	Kaynağı kısmen güncelleme	`PATCH /kullanicilar/42`
DELETE	Kaynağı silme	`DELETE /kullanicilar/42`

GET, PUT ve DELETE "idempotent" (tekrarlanabilir) olacak şekilde tasarlanır: aynı isteği birden fazla kez göndermek sonucu değiştirmez. POST genellikle idempotent değildir; aynı sipariş isteğini iki kez göndermek iki sipariş yaratabilir.

JSON nedir?

JSON (JavaScript Object Notation), insan tarafından okunabilir hafif bir veri biçimidir. Nesneler süslü parantez, listeler köşeli parantez içinde yazılır:

{
  "id": 42,
  "ad": "Ayşe",
  "aktif": true,
  "etiketler": ["blog", "seo"],
  "adres": { "sehir": "İstanbul", "ilce": "Kadıköy" }
}

Dil bağımsızdır; PHP, JavaScript, Python ve birçok dilde kolayca ayrıştırılır (PHP'de json_encode / json_decode).

İstek ve yanıt örneği

curl -X POST https://api.ornek.com/v1/siparisler \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urun_id": 7, "adet": 2}'

HTTP/1.1 201 Created
{ "id": 1042, "durum": "beklemede" }

Yanıtın durum kodu sonucu bildirir: 200 başarılı, 201 oluşturuldu, 400 hatalı istek, 401 kimlik doğrulanmadı, 403 yetkisiz, 404 bulunamadı, 429 çok fazla istek, 500 sunucu hatası. Kodların anlamı için HTTP durum kodları yazımıza göz atın.

Kimlik doğrulama ve yetkilendirme

API anahtarı: İsteğe eklenen gizli bir dizgi; basit ve yaygındır. Hangi uygulamanın istek yaptığını tanımlar ama kullanıcıyı tanımaz.
Bearer token (taşıyıcı belirteç): Authorization: Bearer ... başlığıyla gönderilen, genellikle süreli bir belirteç.
OAuth 2.0: Bir kullanıcının, parolasını paylaşmadan bir uygulamaya kendi verilerine sınırlı erişim yetkisi vermesini sağlayan standart (örneğin "Google ile giriş" veya bir uygulamanın takvimine erişim izni).

API anahtarı güvenliği

Anahtarı istemci tarafı koda (tarayıcıda çalışan JavaScript, mobil uygulama) gömmeyin; kaynak kodu görüntüleyen herkes onu alabilir. Gizli anahtarlar yalnızca sunucuda tutulmalıdır.
Anahtarları kaynak kod deposuna (Git) koymayın; ortam değişkenleri veya gizli yönetim aracı kullanın. Yanlışlıkla yayınlanan anahtarı hemen iptal edip yenileyin; geçmişten silmek yetmez.
Anahtarlara en az yetki verin ve mümkünse IP, alan adı veya API türü kısıtı koyun.
Kullanım kotası ve bütçe uyarısı belirleyin; ücretli API'lerde çalınan anahtar maliyet doğurur.
Her zaman HTTPS kullanın.

API tasarımı ve kullanımında iyi uygulamalar

Sürümleme: /v1/ gibi bir sürümle, eski kullanıcıları bozmadan değişiklik yapabilirsiniz.
Hız sınırlama (rate limiting): Bir istemcinin kısa sürede yapabileceği istek sayısını sınırlar; 429 ve Retry-After başlığıyla bildirilir. İstemci tarafında bu sınırlara uyun ve aşırı istek yerine yeniden deneme için üstel bekleme (exponential backoff) kullanın.
Sayfalama: Büyük listeleri parçalar halinde döndürün (?sayfa=2&adet=50).
Anlamlı hata mesajları: Hata kodu ve açıklaması JSON olarak dönsün.
Belgelendirme: OpenAPI (Swagger) gibi standartlarla makine tarafından okunabilir belge.
Girdi doğrulama: Sunucu tarafında gelen veriyi her zaman doğrulayın (web güvenliği rehberi).

Webhook nedir?

Normalde istemci, bir değişiklik olup olmadığını sormak için sürekli API'yi sorgular (polling). Webhook'ta ise ters yön çalışır: olay gerçekleştiğinde sağlayıcı, sizin belirttiğiniz bir adrese otomatik olarak istek gönderir (örneğin ödeme tamamlandığında ödeme servisinin sitenize bildirim göndermesi). Webhook'ları alırken isteğin gerçekten sağlayıcıdan geldiğini imza doğrulamasıyla kontrol edin.

CORS: tarayıcıdan API çağırırken sık karşılaşılan engel

Tarayıcılar, bir sayfanın başka bir alan adındaki API'ye isteğini varsayılan olarak kısıtlar (aynı kaynak politikası). API sunucusu, Access-Control-Allow-Origin gibi başlıklarla hangi kaynakların erişebileceğini belirtir. Bu bir güvenlik özelliğidir; her yere izin vermek (*) çerezli oturum kullanan API'lerde risk yaratabilir.

Kaynaklar ve ileri okuma

Sık Sorulan Sorular

REST ile SOAP veya GraphQL arasındaki fark nedir?

REST, HTTP yöntemleri ve URL'ler üzerine kurulu hafif bir yaklaşımdır. SOAP, XML tabanlı daha katı ve eski bir protokoldür; GraphQL ise istemcinin tek bir uç noktadan tam olarak istediği alanları sorgulamasına izin verir. Hepsinin farklı kullanım alanları vardır.

Ücretsiz API'ler güvenilir mi?

Kullanım koşullarını, hız sınırlarını, kesinti geçmişini ve gizlilik politikasını okuyun. Ücretsiz bir servise iş açısından kritik bağımlılık kurmak, hizmetin değişme veya kapanma riski taşır; bir yedek planınız olsun.

API anahtarım yanlışlıkla herkese açık bir yerde yayınlandı, ne yapmalıyım?

Anahtarı hemen iptal edip yenisini oluşturun, hizmetin kullanım günlüklerinde şüpheli etkinlik arayın ve yeni anahtarı güvenli biçimde (sunucu ortam değişkeni gibi) saklayın.