API Nedir?
Kısa tanım
API (Application Programming Interface, Uygulama Programlama Arayüzü), bir yazılımın başka yazılımlara hangi işlevleri ve verileri hangi kurallarla sunduğunu tanımlayan arayüzdür. API; çağrılabilecek işlemleri, gönderilecek parametreleri, dönecek yanıtların formatını ve hata durumlarını belirleyen bir sözleşme gibi çalışır. Böylece iki sistem birbirinin iç yapısını bilmeden veri alışverişi yapabilir; örneğin bir e-ticaret sitesi ödeme veya kargo firmasının sistemine API üzerinden bağlanır.
Diğer adları: Uygulama Programlama Arayüzü, Application Programming Interface
Arayüz bir sözleşmedir
Bir API, iki yazılımın birbirinin iç yapısını bilmeden nasıl konuşacağını tarif eder: hangi işlemlerin çağrılabileceğini, parametrelerin hangi formatta gönderileceğini, karşılığında ne döneceğini ve bir şeyler ters gittiğinde nasıl davranılacağını. Bu yüzden API'yi bir program parçasından çok bir sözleşme olarak düşünmek daha doğrudur. Sözleşmenin arkasındaki kod baştan yazılabilir, veritabanı değiştirilebilir; arayüz aynı kaldığı sürece onu kullanan uygulamalar bundan etkilenmez.
Günlük hayattaki entegrasyonların çoğu bu ayrıma dayanır. Bir e-ticaret sitesi kargo firmasının iç sistemlerine erişmeden gönderi oluşturabilir, bir muhasebe programı bankanın veritabanını görmeden hesap hareketlerini çekebilir. İki tarafın paylaştığı tek şey yazılı ve sürümlenmiş bir arayüzdür.
API türleri
“API” kelimesi çoğunlukla web servisleri için kullanılsa da kavram çok daha geniştir:
- Kütüphane ve framework API'leri: Bir programlama dilinin standart kütüphanesindeki fonksiyonlar ya da bir paketin dışarıya açtığı sınıf ve metotlar. Çağrı aynı program içinde, ağ kullanılmadan gerçekleşir.
- İşletim sistemi API'leri: Dosya okuma, ağ bağlantısı açma veya bellek ayırma gibi işler için uygulamaların işletim sistemine yaptığı çağrılar.
- Tarayıcı API'leri:
fetch,localStorageveya Geolocation gibi, tarayıcının JavaScript koduna sunduğu arayüzler. - Web API'leri: Ağ üzerinden, genellikle HTTP ile erişilen servisler. Ödeme altyapıları, harita servisleri, CRM ve ERP sistemleri işlevlerini çoğunlukla bu yolla dışarıya açar.
Web API'lerinde yaygın yaklaşımlar
| Yaklaşım | Temel fikir | Tipik kullanım |
|---|---|---|
| REST | Kaynaklar URL ile adreslenir, HTTP metotlarıyla işlenir | Genel amaçlı ve herkese açık web API'leri |
| GraphQL | İstemci tek bir uç noktaya, ihtiyaç duyduğu alanları tarif eden bir sorgu gönderir | Farklı ekranların farklı veri şekillerine ihtiyaç duyduğu arayüzler |
| gRPC | Protocol Buffers ile tanımlanan, HTTP/2 üzerinde çalışan uzaktan prosedür çağrısı | Servisler arasındaki düşük gecikmeli iç iletişim |
| SOAP | WSDL ile tanımlanan, XML tabanlı katı mesaj formatı | Bankacılık ve kamu gibi alanlardaki eski kurumsal entegrasyonlar |
Bunların en yaygını olan REST API yaklaşımının kuralları ayrı bir maddede anlatılıyor. Tablodaki yaklaşımların hepsi istemcinin istek gönderip yanıt beklediği modele dayanır. Karşı tarafın bir olay gerçekleştiğinde sizi kendiliğinden haberdar ettiği modelin adı ise webhook'tur.
İyi bir API'yi ne belirler?
- Belgeleme: Uç noktalar, alanlar ve hata kodları eksiksiz yazılmalıdır. Web API'leri için OpenAPI Specification makinece okunabilir bir tanım formatı sunar; bu tanımdan dokümantasyon, test ve istemci kodu üretilebilir.
- Sürümleme: Var olan bir alanı kaldırmak ya da anlamını değiştirmek, onu kullanan herkesi bozar. Kırıcı değişiklikler yeni bir sürümle (ör.
/v2/) yayımlanmalı, eski sürüm bir geçiş süresi boyunca korunmalıdır. - Güvenlik: Kimin hangi veriye erişebileceği API anahtarları, OAuth veya token tabanlı yöntemlerle denetlenir. Bir arayüz ağa açıldığı anda saldırı yüzeyinin parçası olur.
- Öngörülebilir hatalar: Hata yanıtları tutarlı bir yapıda olmalı, istemcinin sorunu anlayıp düzeltmesine yetecek bilgiyi vermeli, ama iç sistem ayrıntılarını sızdırmamalıdır.
- Limitler: Hız sınırları (rate limit) ve sayfalama, tek bir istemcinin bütün sistemi yavaşlatmasını önler.
Sık karşılaşılan yanlış anlamalar
“API bir sunucudur.” API, sunucunun dışarıya açtığı kapıların tarifidir. Aynı sunucu hem bir web sitesi yayınlayıp hem de bir API sunabilir.
“API'si varsa entegrasyon hazırdır.” Bir sistemin API'si olması, ihtiyaç duyduğunuz veriyi veya işlemi sunduğu anlamına gelmez. Entegrasyon planlanırken gereken uç noktaların gerçekten var olup olmadığı, kullanım limitleri ve verinin ne sıklıkla güncellendiği baştan kontrol edilmelidir.
“Her API herkese açıktır.” API'lerin büyük bölümü özeldir: yalnızca bir şirketin mobil uygulaması ile kendi sunucusu arasında ya da bir mikroservis mimarisindeki servisler arasında kullanılır ve dışarıdan erişilemez.