API Nedir? Her Geliştiricinin Gerçekten Anlaması Gereken Kavram

Bugün bir API kullandınız. Muhtemelen onlarcasını. Bu sabah hava durumu uygulamasını açtığınızda, bir web sitesine Google ile giriş yaptığınızda, bir push bildirimi aldığınızda — bunların hepsi perde arkasında API'lerin birbirleriyle konuşmasıydı.

Ama junior geliştiricilere "API nedir?" diye sorulduğunda cevap genellikle şu olur: "Uygulamaların birbirleriyle iletişim kurma şekli." Bu yanlış değil. Ama arabayı "hareket eden bir şey" olarak tanımlamak gibi. Teknik olarak doğru. Bir şey bozulduğunda tamamen işe yaramaz.

Bu yazı, gerçekten ihtiyacınız olan zihinsel modeli inşa ediyor.

Kelimeden Başlayalım

API, Application Programming Interface kelimelerinin kısaltmasıdır. Türkçesi: Uygulama Programlama Arayüzü. Parçalara ayıralım:

Application (Uygulama) — belirli bir işlevi olan herhangi bir yazılım. Bir hava durumu uygulaması, bir ödeme sistemi, kendi backend'iniz.

Programming (Programlama) — doğrudan insanlar tarafından değil, kod tarafından kullanılmak üzere tasarlanmış.

Interface (Arayüz) — tanımlanmış bir sınır. Bir sözleşme. İki şeyin nasıl etkileşime girebileceğine dair kurallar bütünü.

Anahtar kelime arayüz. API, bir sistemin içindeki mantık değil — o sisteme açılan kapı. Ne isteyebileceğinizi, nasıl isteyebileceğinizi ve geri ne alacağınızı tanımlar.

Bir restoran düşünün. Mutfağa girip kendi yemeğinizi pişirmezsiniz. Menü ve garson aracılığıyla etkileşime girersiniz — bu arayüzdür. Mutfak (asıl mantık) sizden gizlidir. Makarnanın nasıl yapıldığını bilmenize gerek yok. Sadece nasıl sipariş vereceğinizi bilmeniz yeterli.

API'ler Neden Var

API'ler standartlaşmadan önce yazılım sistemleri sıkı sıkıya bağlıydı. A Şirketi B Şirketi ile veri paylaşmak istediğinde, genellikle yalnızca o ikili için özel entegrasyon kodu yazılırdı. Bir sistemi değiştirin, entegrasyon bozulur. 10 sisteme ölçeklendirin, bakım kabusu yaşarsınız.

API'ler sabit sözleşmeler oluşturarak bunu çözdü. API sözleşmesi değişmediği sürece, sistemin içinde ne olduğu önemli değil. Tüm veritabanınızı yeniden yazabilir, programlama dilini değiştirebilir, yeni bir sunucuya taşınabilirsiniz — dış dünya hiçbir fark görmez.

Bu kapsülleme prensibidir ve yazılım mühendisliğindeki en güçlü fikirlerden biridir.

HTTP: Web API'lerinin Dili

Bir web geliştiricisi olarak çalışacağınız API'lerin çoğu HTTP API'leri — tarayıcınızın web sayfalarını yüklemek için kullandığı protokol üzerinden iletişim kuruyorlar.

Tarayıcıya https://example.com yazdığınızda, tarayıcınız bir sunucuya HTTP isteği gönderir ve karşılığında HTTP yanıtı alır. API'ler tam olarak aynı şekilde çalışır — sadece tarayıcı HTML oluşturmaz.

Bir HTTP isteğinin birkaç temel parçası var:

Method (Metod) — gerçekleştirmek istediğiniz eylem türü:

GET     → veri çekme
POST    → yeni bir şey oluşturma
PUT     → mevcut veriyi tamamen güncelleme
PATCH   → mevcut veriyi kısmen güncelleme
DELETE  → bir şeyi silme

URL (Endpoint) — isteği gönderdiğiniz yer. Adres gibi düşünün.

Headers (Başlıklar) — istek hakkında metadata. Kimlik doğrulama token'ları, içerik türü, kabul edilen yanıt formatı gibi şeyler.

Body (Gövde) — gönderdiğiniz veri (POST, PUT, PATCH'te kullanılır). Her isteğin gövdesi olmaz — GET isteğinin genellikle gövdesi yoktur.

Gerçek dünyadan örnek. Bir hava durumu uygulaması şehrinizin tahminini çektiğinde, perde arkasında şuna benzer bir şey yapıyor:

GET https://api.weather.com/v1/forecast?city=Istanbul
Authorization: Bearer api_key_buraya

Sunucu bunu işler, İstanbul'un tahmin verilerini bulur ve genellikle JSON formatında bir yanıt gönderir.

JSON: Evrensel Dil

JSON (JavaScript Object Notation), çoğu API'nin veri göndermek ve almak için kullandığı format. Şöyle görünür:

{
  "sehir": "İstanbul",
  "sicaklik": 18,
  "durum": "Parçalı Bulutlu",
  "nem": 65,
  "tahmin": [
    { "gun": "Pazartesi", "en_yuksek": 20, "en_dusuk": 13 },
    { "gun": "Sali", "en_yuksek": 17, "en_dusuk": 11 }
  ]
}

İnsan tarafından okunabilir, neredeyse her programlama dilinde kolayca işlenebilir ve ağ üzerinden verimli biçimde gönderilebilecek kadar hafif. JSON'dan önce baskın format XML'di — çok daha ayrıntılı ve çalışması zordu.

REST: Çoğu API'nin Takip Ettiği Mimari Stil

REST API veya RESTful API terimini sıkça duyacaksınız. REST, Representational State Transfer anlamına gelir — Roy Fielding tarafından 2000 yılındaki doktora tezinde tanımlanan mimari prensipler bütünü.

REST bir protokol ya da standart değil. Bir stil. Uyulduğunda API'leri öngörülebilir, ölçeklenebilir ve anlaşılır kılan kısıtlamalar bütünü.

Pratikte en çok önem taşıyan temel kısıtlamalar:

Durumsuzluk (Statelessness) — her istek, sunucunun onu işlemesi için gereken tüm bilgiyi içermelidir. Sunucu önceki istekler hakkında hiçbir şey hatırlamaz. Bu yüzden kimlik doğrulama token'ınızı yalnızca ilk istekte değil, her istekte gönderirsiniz.

Tekdüze Arayüz (Uniform Interface) — kaynaklar URL'lerle tanımlanır ve standart HTTP metodlarıyla etkileşime girilir. GET /users/42 görürsem, ne yaptığını tahmin etmek için dokümantasyona ihtiyacım yok.

İstemci-Sunucu Ayrımı — frontend ve backend birbirinden bağımsız. Backend'e dokunmadan tüm frontend'i yeniden oluşturabilirsiniz, ya da tam tersi.

İyi REST URL tasarımı şöyle görünür:

GET    /articles        → tüm makaleleri listele
GET    /articles/7      → ID'si 7 olan makaleyi getir
POST   /articles        → yeni makale oluştur
PUT    /articles/7      → makale 7'yi tamamen değiştir
PATCH  /articles/7      → makale 7'nin belirli alanlarını güncelle
DELETE /articles/7      → makale 7'yi sil

İsim (kaynak) URL'de. Fiil (eylem) HTTP metodunda. Düzgün bir REST API'de /getArticle veya /deleteUser görmezsiniz — metod zaten o anlamı taşıyor.

HTTP Durum Kodları: API'nin Geri Konuşma Şekli

Sunucu yanıt verdiğinde bir durum kodu ekler — isteğin başarılı olup olmadığını söyleyen üç haneli bir sayı.

2xx — Başarı. 200 OK (istek çalıştı), 201 Created (yeni kaynak oluşturuldu), 204 No Content (çalıştı, döndürülecek bir şey yok).

3xx — Yönlendirme. Kaynak taşındı. İstemciniz yeni konumu takip etmeli.

4xx — İstemci hataları. Siz bir şeyi yanlış yaptınız. 400 Bad Request (hatalı veri), 401 Unauthorized (geçerli kimlik bilgisi yok), 403 Forbidden (izniniz yok), 404 Not Found (kaynak mevcut değil).

5xx — Sunucu hataları. Sunucu bir şeyi yanlış yaptı. 500 Internal Server Error (bir şey çöktü), 503 Service Unavailable (sunucu aşırı yüklenmiş).

Durum kodlarını anlamak, debug etmeyi tahmin etmekten teşhis etmeye dönüştürür. 401 gördüğünüzde istek gövdesini değil, kimlik doğrulama başlıklarını kontrol edersiniz.

API Anahtarları ve Kimlik Doğrulama

Çoğu genel API kendinizi tanıtmanızı ister. En yaygın mekanizma API anahtarı — hesabınıza bağlı ve her istekle birlikte gönderdiğiniz benzersiz bir dize.

GET https://api.example.com/data
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Modern API kimlik doğrulaması için yaygın standart JWT (JSON Web Token). Kullanıcı hakkındaki bilgileri doğrulanabilir, değiştirilemez bir formatta kodlar. Sunucunun oturum aramasına gerek yok — sadece token imzasını doğrular.

API anahtarlarını hiçbir zaman frontend kodunda açığa çıkarmayın ya da git'e commit etmeyin. Ortam değişkenlerine, sunucu tarafına koyun.

İyi Bir API'yi Ne Yapar

İyi bir API öngörülebilir. Dokümantasyonu okumadan önce endpoint'in nasıl çalıştığını tahmin edebilirsiniz. Hatalar açıklayıcıdır — sadece 400 Bad Request değil, 400: email alanı geçerli bir e-posta adresi olmalıdır gibi.

İyi bir API versiyonlanmış. Kırıcı değişiklikler /v2/'de yaşarken /v1/ çalışmaya devam eder. Bir sabah entegrasyonunuzun bozulduğunu görmek üzere uyanmazsınız.

İyi bir API'nin iyi dokümantasyonu vardır. Stripe'ın API dokümantasyonu altın standart olarak gösterilir — her endpoint gerçek örnekler, hata durumları ve birden fazla dilde kod snippet'leriyle belgelenmiş.

API'ler Bakmadığınız Her Yerde

Kavram web servislerinin çok ötesine uzanır. İşletim sisteminizin API'leri var — bir uygulama dosya okumak istediğinde OS API'lerini çağırır. Tarayıcınızın API'leri var — document.querySelector(), fetch(), localStorage hepsi tarayıcının JavaScript API'sinin parçası. Donanımın bile API'leri var — grafik kartınız oyun motorlarının kullandığı Vulkan veya Metal gibi API'leri açığa çıkarır.

Zihinsel modeli bir kez edindiğinizde — iki bileşen arasında tanımlanmış bir sözleşme — API'leri her yerde görmeye başlarsınız.

Menüyü ne kadar iyi anlarsanız, tam olarak istediğinizi o kadar güvenle sipariş edebilirsiniz — ve bir şeyler yanlış gittiğinde ne kadar hızlı anlarsınız.