API Nedir? Nasıl Çalışır? Başlangıç Rehberi

Bir hava durumu uygulamasının bulunduğunuz şehirdeki sıcaklığı göstermesi, e-ticaret sitesinin ödeme kuruluşuyla iletişim kurması veya mobil uygulamanın kullanıcı bilgilerini sunucudan alması çoğu zaman API’ler sayesinde gerçekleşir.

API’ler, günümüzde kullandığımız yazılımların görünmeyen bağlantı noktalarıdır. Bir uygulamanın başka bir uygulamadan veri almasını, işlem başlatmasını veya belirli bir özelliği güvenli ve kontrollü biçimde kullanmasını sağlar.

Bu rehberde API’nin ne olduğunu, nasıl çalıştığını, temel kavramlarını ve günlük hayatta nerelerde kullanıldığını teknik ayrıntılarda kaybolmadan ele alacağız.

API nedir?

API, İngilizce “Application Programming Interface” ifadesinin kısaltmasıdır. Türkçede genellikle “Uygulama Programlama Arayüzü” olarak karşılanır.

En basit tanımıyla API, iki yazılımın birbiriyle nasıl iletişim kuracağını belirleyen kurallar bütünüdür. Bir yazılım başka bir sistemden veri isterken veya o sistemde işlem yapmak isterken API tarafından tanımlanan yöntemleri kullanır.

API, karşı taraftaki uygulamanın bütün kaynak kodunu ya da veritabanını açmaz. Yalnızca izin verilen verilere ve işlemlere belirlenmiş kurallar üzerinden erişim sağlar.

API nasıl çalışır?

API çalışma mantığını bir restorandaki müşteri, garson ve mutfak ilişkisine benzetebiliriz.

Müşteri, bir istekte bulunan uygulamadır.
Garson, isteği ilgili sisteme taşıyan API’dir.
Mutfak, işlemin gerçekleştirildiği sunucu veya hizmettir.
Hazırlanan yemek ise uygulamaya dönen yanıttır.

Müşterinin yemeğin nasıl pişirildiğini veya mutfağın nasıl düzenlendiğini bilmesi gerekmez. Menüden ne isteyebileceğini görür, siparişini verir ve sonucunu alır. API de yazılımlara buna benzer, sınırları belirlenmiş bir iletişim yöntemi sunar.

Tipik bir API işleminde şu adımlar gerçekleşir:

İstemci uygulama belirli bir adrese istek gönderir.
API, isteğin biçimini ve yetkisini kontrol eder.
Sunucu gerekli işlemi gerçekleştirir.
Sonuç, belirli bir veri biçiminde istemciye gönderilir.
İstemci uygulama gelen yanıtı kullanıcıya gösterir veya başka bir işlemde kullanır.

API isteği ve API yanıtı nedir?

Bir uygulamanın API’ye gönderdiği mesaja istek, API’nin geri gönderdiği sonuca ise yanıt denir.

Örneğin bir mağaza uygulaması, kimliği 42 olan ürünün bilgilerini almak için aşağıdakine benzer bir istek gönderebilir:

GET /api/products/42

API, ürün bulunduğunda buna benzer bir JSON yanıtı döndürebilir:

{
  "id": 42,
  "name": "Kablosuz Klavye",
  "price": 1499.90,
  "available": true
}

Uygulama bu veriyi aldıktan sonra ürün adını, fiyatını ve stok durumunu kullanıcı arayüzünde gösterebilir.

Buradaki önemli nokta, uygulamanın veritabanına doğrudan bağlanmamasıdır. İstemci yalnızca API’nin izin verdiği alanlara ve işlemlere erişir.

Endpoint nedir?

Endpoint, API üzerinde belirli bir veriye veya işleme ulaşmak için kullanılan adrestir. Aynı API içerisinde kullanıcılar, ürünler, siparişler veya ödemeler için farklı endpoint’ler bulunabilir.

Örnek olarak:

/api/products ürün listesini temsil edebilir.
/api/products/42 belirli bir ürünü temsil edebilir.
/api/orders siparişlerle ilgili işlemler için kullanılabilir.
/api/users/me oturum açan kullanıcının profilini döndürebilir.

Endpoint adresinin yanında kullanılan HTTP metodu da hangi işlemin istendiğini belirtir.

API’lerde kullanılan HTTP metotları

Web API’lerinde en sık kullanılan HTTP metotları şunlardır:

GET: Bir kaynağı veya veri listesini almak için kullanılır.
POST: Yeni bir kayıt ya da işlem oluşturmak için kullanılır.
PUT: Mevcut bir kaynağın tamamını güncellemek için kullanılabilir.
PATCH: Kaynağın yalnızca belirli alanlarını güncellemek için kullanılır.
DELETE: Bir kaynağı silmek için kullanılır.

Örneğin GET /api/products/42 ürünün bilgilerini isterken, DELETE /api/products/42 aynı ürünün silinmesini talep edebilir. Gerçek işlemin yapılıp yapılmayacağı kullanıcının yetkisine ve API kurallarına bağlıdır.

HTTP durum kodları ne anlama gelir?

API yanıtlarında işlemin sonucunu anlatan HTTP durum kodları bulunur. En sık karşılaşılanlardan bazıları şunlardır:

200 OK: İstek başarıyla tamamlandı.
201 Created: Yeni bir kayıt başarıyla oluşturuldu.
400 Bad Request: Gönderilen istekte eksik veya hatalı bilgi bulunuyor.
401 Unauthorized: Kimlik doğrulaması gerekli veya gönderilen bilgiler geçersiz.
403 Forbidden: Kullanıcı tanınsa bile bu işlem için yeterli yetkiye sahip değil.
404 Not Found: İstenen kaynak bulunamadı.
429 Too Many Requests: Belirlenen istek sınırı aşıldı.
500 Internal Server Error: Sunucu tarafında beklenmeyen bir hata oluştu.

İyi geliştirilmiş bir uygulama yalnızca başarılı yanıtları değil, hata durumlarını da doğru biçimde ele almalıdır.

API anahtarı ve kimlik doğrulama

Her API herkese açık değildir. Birçok sistem, isteği gönderen uygulamanın veya kullanıcının kim olduğunu doğrulamak ister.

API’lerde yaygın olarak şu yöntemlerle karşılaşılır:

API anahtarı: Uygulamaya verilen özel bir erişim anahtarıdır.
Bearer token: Genellikle kullanıcı oturumu veya yetkili uygulama erişimi için kullanılır.
OAuth: Kullanıcının şifresini başka bir uygulamayla paylaşmadan belirli izinler vermesini sağlar.
Temel kimlik doğrulama: Kullanıcı adı ve parola temelli daha basit bir yöntemdir; mutlaka güvenli bağlantıyla kullanılmalıdır.

API anahtarları ve erişim token’ları herkese açık JavaScript dosyalarına, mobil uygulama kaynaklarına veya herkese açık kod depolarına yazılmamalıdır. Hassas bilgiler mümkün olduğunca sunucu tarafında saklanmalıdır.

REST API nedir?

REST, web tabanlı API’lerde sık kullanılan bir mimari yaklaşımdır. REST API’ler çoğunlukla HTTP metotlarını kullanır ve verileri JSON biçiminde gönderir.

REST bir programlama dili veya hazır yazılım değildir. Kaynakların adreslerle temsil edilmesi, işlemlerin standart HTTP davranışlarıyla gerçekleştirilmesi ve istemci ile sunucunun birbirinden ayrılması gibi ilkeler sunar.

Her JSON döndüren endpoint kusursuz bir REST API sayılmaz. Buna rağmen günlük kullanımda HTTP üzerinden çalışan pek çok web servisi genel olarak REST API adıyla anılır.

Başka hangi API türleri vardır?

REST yaygın olsa da tek API yaklaşımı değildir.

SOAP: XML tabanlı, daha katı kurallara sahip bir web servisi yaklaşımıdır.
GraphQL: İstemcinin ihtiyaç duyduğu alanları daha ayrıntılı biçimde seçebilmesine imkân verir.
WebSocket: İstemci ile sunucu arasında sürekli ve çift yönlü iletişim kurulmasını sağlar.
RPC: Uzak bir sistemdeki fonksiyon veya prosedürün çağrılmasına odaklanır.

Hangi yöntemin kullanılacağı projenin ihtiyaçlarına, mevcut altyapıya, performans beklentilerine ve ekip deneyimine göre belirlenir.

API’ler nerelerde kullanılır?

API kullanım alanı oldukça geniştir. Günlük hayatta fark etmeden kullandığımız pek çok hizmet, arka planda birden fazla API ile iletişim kurar.

Ödeme kuruluşlarıyla güvenli ödeme işlemleri
Kargo takibi ve teslimat bilgilerinin alınması
Harita, konum ve rota hizmetleri
Hava durumu verilerinin gösterilmesi
E-posta ve SMS gönderimi
Sosyal medya hesaplarıyla oturum açma
Döviz kuru ve finansal veri aktarımı
Yapay zekâ modellerine metin veya görsel gönderilmesi
Mobil uygulama ile web sunucusu arasındaki iletişim
Farklı şirket yazılımları arasında veri senkronizasyonu

Örneğin bir restoran yazılımı menü bilgilerini mobil uygulamaya aktarabilir, siparişi mutfak ekranına gönderebilir ve ödeme sonucunu farklı bir hizmetten alabilir. Kullanıcı tek bir uygulama görse de arka planda birçok sistem birlikte çalışabilir.

API ile SDK arasındaki fark nedir?

API, bir sistemle nasıl iletişim kurulacağını tanımlar. SDK ise belirli bir platform veya hizmet için geliştirme yapmayı kolaylaştıran araçlar paketidir.

Bir SDK içerisinde hazır fonksiyonlar, kod kütüphaneleri, örnek projeler, test araçları ve dokümantasyon bulunabilir. SDK çoğu zaman ilgili API’ye daha kolay erişebilmek için hazırlanır.

Kısacası API iletişim kurallarını, SDK ise bu kuralları kullanmayı kolaylaştıran geliştirme araçlarını ifade eder.

API ile web servisi aynı şey mi?

Bu iki kavram birbirine yakın olsa da tamamen aynı değildir. Web servisi, ağ üzerinden iletişim kuran bir hizmettir. API ise yalnızca internet üzerinden çalışan servisleri değil, bir yazılım kütüphanesinin sunduğu fonksiyonları veya işletim sisteminin programlara açtığı özellikleri de kapsayabilir.

Bu nedenle her web servisi bir API olarak değerlendirilebilirken her API’nin web servisi olması gerekmez.

İyi bir API’nin özellikleri nelerdir?

Bir API’nin yalnızca çalışması yeterli değildir. Geliştiriciler tarafından güvenli ve sürdürülebilir biçimde kullanılabilmesi gerekir.

İyi bir API genellikle şu özelliklere sahiptir:

Tutarlı endpoint ve alan isimleri kullanır.
Anlaşılır ve güncel dokümantasyon sunar.
Başarı ve hata durumlarında doğru durum kodları döndürür.
Kimlik doğrulama ve yetkilendirmeyi birbirinden ayırır.
Gönderilen verileri sunucu tarafında doğrular.
İstek sınırlandırması ve kötüye kullanım önlemleri uygular.
Sürüm değişikliklerini kontrollü biçimde yönetir.
Gereksiz veya hassas verileri yanıta eklemez.

API tasarımı yalnızca teknik bir konu değildir. İyi tasarlanmış bir API, onu kullanacak geliştiricinin daha az hata yapmasını ve entegrasyonu daha kısa sürede tamamlamasını sağlar.

Yapay zekâ API geliştirmeyi kolaylaştırır mı?

Yapay zekâ araçları endpoint taslağı oluşturma, örnek istek hazırlama, dokümantasyon yazma ve hata mesajlarını yorumlama gibi görevlerde yardımcı olabilir. Ancak üretilen kodun güvenlik, yetkilendirme ve veri doğrulama açısından kontrol edilmesi gerekir.

Özellikle API anahtarlarının korunması, kullanıcı yetkilerinin denetlenmesi ve hassas verilerin filtrelenmesi geliştiricinin sorumluluğundadır. Yapay zekâ ile geliştirmenin avantajlarını ve risklerini ayrıca Vibe Coding nedir? makalesinde inceleyebilirsiniz.

Sık sorulan sorular

API kullanmak için programlama bilmek gerekir mi?

API’nin ne yaptığını anlamak için ileri düzey programlama bilgisi gerekmez. Ancak bir API’yi yazılıma entegre etmek için kullanılan dile, HTTP isteklerine ve veri biçimlerine ilişkin temel bilgi gerekir.

API kullanımı ücretli midir?

API’ye göre değişir. Bazı hizmetler tamamen ücretsizdir, bazıları belirli bir kullanım kotasına kadar ücretsiz hizmet verir. Ticari API’ler ise istek sayısı, kullanılan özellik veya işlenen veri miktarı üzerinden ücretlendirme yapabilir.

API anahtarı paylaşılabilir mi?

API anahtarları genellikle gizli tutulmalıdır. Anahtarın paylaşılması, başkalarının sizin kullanım hakkınızla işlem yapmasına ve beklenmeyen maliyetler oluşmasına yol açabilir.

JSON nedir?

JSON, sistemler arasında veri taşımak için kullanılan, insan tarafından okunması görece kolay bir metin biçimidir. Modern web API’lerinin büyük bölümü istek ve yanıt verilerinde JSON kullanır.

Bir API çalışmazsa ne olur?

API geçici olarak erişilemezse ona bağlı özellikler de çalışmayabilir. Bu nedenle uygulamalarda zaman aşımı, yeniden deneme, hata kaydı ve kullanıcıya anlaşılır mesaj gösterme gibi önlemler bulunmalıdır.

Sonuç

API, farklı yazılımların güvenli ve belirlenmiş kurallar üzerinden iletişim kurmasını sağlayan bir arayüzdür. Mobil uygulamalardan ödeme sistemlerine, kargo takibinden yapay zekâ hizmetlerine kadar pek çok teknolojinin temelinde API’ler bulunur.

API mantığını anlamak için ilk aşamada endpoint, istek, yanıt, HTTP metodu, durum kodu ve kimlik doğrulama kavramlarını öğrenmek yeterlidir. Bu temel kavramlar anlaşıldığında farklı API dokümantasyonlarını okumak ve entegrasyon süreçlerini takip etmek çok daha kolay hâle gelir.

API Nedir? Nasıl Çalışır ve Ne İşe Yarar?