API Nedir? İstekten Cevaba Uygulama İletişimi

API'nin sınırı: Kod paylaşmak değil, yetenek sunmak

API'nin temel görevi, bir yazılımın belirli veri veya işlevlerini başka bir yazılımın kullanabileceği biçimde dışarıya açmaktır. Örneğin bir hava durumu servisi, kendi veri toplama ve hesaplama süreçlerini paylaşmadan sıcaklık sorgulama işlevi sunabilir. İstemci yalnızca API'nin izin verdiği sorguyu yapar; sunucunun veritabanına veya iç koduna doğrudan erişmez.

Bu ayrım önemlidir: API, uygulamanın tamamını dışarı açmak zorunda değildir. Bir not uygulaması kendi içinde çalışabilir ve dışarıya hiçbir API sunmayabilir. Buna karşılık ödeme, harita veya sosyal giriş gibi başka uygulamalarla birleşmesi gereken servisler kontrollü bir arayüz tasarlayabilir.

Bir API'yi anlamak için şu dört soruyu sormak yararlıdır:

1. Hangi işlev veya veri dışarıya açılıyor?
2. İstemci isteği hangi adrese ve hangi biçimde gönderecek?
3. Sunucu başarılı durumda ne döndürecek?
4. Yetkisiz, hatalı veya eksik istekte ne olacak?

Bu soruların cevabı belirsizse ortada yalnızca teknik bir bağlantı değil, kullanımı tanımlanmamış bir servis vardır. API dokümantasyonu bu sözleşmeyi geliştiriciye açıklar.

Bir API isteğini oluşturan parçalar

Bir API iletişiminde istemci, sunucuya rastgele bir mesaj göndermez. İstek genellikle belirli bir endpoint, istenen işlem, parametreler ve gerektiğinde kimlik bilgileri içerir. Endpoint, belirli bir kaynağa veya işlev grubuna ulaşmak için kullanılan adres olarak düşünülebilir. Örneğin bir hava durumu API'sinde şehir bilgisi alan bir endpoint, belirli bir konumun verisini istemek için kullanılabilir.

Sorgu parametreleri ve gövde, istek verisinin yaygın olarak taşındığı iki alandır. Sorgu parametresi, adresin yanında gönderilen küçük seçim bilgileridir; örneğin şehir veya dil tercihi. Gövde ise özellikle yeni bir kayıt oluşturma ya da daha kapsamlı veri gönderme sırasında kullanılan bölümdür. Bununla birlikte istekler yol parametreleri, başlıklar, çerezler ve kullanılan protokole özgü başka alanlar da içerebilir; kimlik bilgileri de çoğu zaman başlıklarda taşınır. Multipart/form-data, gövde için kullanılabilen biçimlerden biridir. Kaynak makalede belirtildiği gibi JSON ve XML, istek veya cevap verilerinin taşınabildiği biçimler arasındadır. Güncel bir API'nin hangi biçimi kabul ettiği, API'nin kendi sözleşmesine bağlıdır.

Basitleştirilmiş istek şeması şöyledir:

İstemci → endpoint + işlem + parametreler + gerekiyorsa yetki bilgisi → Sunucu

Cevap da yalnızca 'oldu' anlamına gelen bir metin değildir. Genellikle işlemin başarılı olup olmadığını, istenen veriyi veya hatanın nedenini açıklayan yapılandırılmış bir içerik döndürür. İstemci bu cevabı okuyarak ekranda sonuç gösterebilir, hata mesajı verebilir veya başka bir işlem başlatabilir.

İstek-cevap döngüsünde istemci, API ve sunucu rolleri

API iletişimini beş aşamalı bir döngüyle inceleyebiliriz:

1. İstemci isteği hazırlar: Kullanıcı bir işlem başlatır; örneğin bir şehir için hava durumu sorgular. Uygulama, API'nin beklediği alanları kullanarak isteği oluşturur.
2. İstek API adresine gönderilir: İstemci, tanımlanmış endpoint'e ulaşır. İstek biçimi ve gerekli bilgiler API sözleşmesine uygun olmalıdır.
3. İstemci, API sözleşmesine uygun isteği endpoint'e gönderir. Endpoint'in arkasındaki sunucu uygulaması isteği işler; uygulama mantığına veya gerekli veri kaynaklarına erişebilir, veri bulabilir, işlem yapabilir ya da isteği reddedebilir.
4. Cevap hazırlanır: Sunucu sonucu API üzerinden istemciye gönderir. Cevap, başarı durumunda istenen veriyi; başarısız durumda ise sorunun niteliğini içerebilir.
5. İstemci sonucu yorumlar: Uygulama cevabı kullanıcı arayüzüne dönüştürür. Veri eksikse, erişim reddedilmişse veya servis yanıt vermemişse uygun bir davranış seçmelidir.

Bu akışın kritik noktası, API'nin iki taraf arasında ortak bir dil kurmasıdır. İstemcinin JavaScript, Python veya başka bir dille yazılması tek başına yeterli değildir; doğru endpoint, doğru veri biçimi ve doğru erişim kuralları da gerekir. Bu nedenle <slug: python-nedir> ve <slug: javascript-nedir> gibi programlama dili konuları API kullanımının kodlama tarafını anlamaya yardımcı olur.

Çözümlü örnek: Şehir hava durumu sorgusunu okumak

Aşağıdaki örnek gerçek bir servis adı veya gerçek bir erişim adresi vermek için değil, bir API akışının nasıl çözümleneceğini göstermek için hazırlanmıştır.

Verilenler:

• İstemci: Bir hava durumu uygulaması
• İstenen işlem: Ankara için güncel hava durumu bilgisini almak
• Veri biçimi: JSON
• Gerekli bilgi: Şehir adı
• API'nin izin verdiği varsayılan endpoint: /weather

Çözüm adımları:

1. İstemci, kullanıcının seçtiği şehir bilgisini alır. Bu örnekte parametre city=Ankara olur.
2. Uygulama, endpoint ile parametreyi API sözleşmesine uygun biçimde birleştirir. Kavramsal istek /weather?city=Ankara şeklinde gösterilebilir.
3. API isteği hava durumu sunucusuna iletir. Burada API'nin görevi sıcaklığı kendi başına tahmin etmek değil, isteği doğru servise ulaştırmak ve cevabı geri sunmaktır.
4. Sunucu, Ankara için veri bulursa JSON biçiminde bir cevap döndürür. Örnek cevap yapısı şöyle olabilir:

{\"city\":\"Ankara\",\"temperature\":18,\"unit\":\"C\"}

5. İstemci JSON içindeki alanları okur. city alanı konumu, temperature sayısal değeri, unit ise bu sayının hangi ölçü biriminde olduğunu belirtir. Uygulama ekranda 'Ankara: 18 °C' gösterebilir.
6. Cevapta veri bulunamazsa uygulama bunu başarılı sonuç gibi göstermemelidir. Şehir adı eksikse kullanıcıdan seçim istenebilir; servis erişilemiyorsa daha sonra yeniden deneme veya bilgilendirme yapılabilir.

Sonuç: Kullanıcı yalnızca hava durumu uygulamasını görür; veri üretme ve sunma görevi ise API'nin arkasındaki serviste gerçekleşir. Uygulamanın doğru çalışması, endpoint'in, parametrenin ve cevap alanlarının API sözleşmesine uygun okunmasına bağlıdır.

Çözümlü örnek: Sosyal hesapla girişte veri akışı

Verilenler:

• İstemci: Bir etkinlik uygulaması
• Kullanıcı işlemi: Sosyal hesapla giriş seçeneğine dokunmak
• Harici servis: Kimliği doğrulayan sosyal platform
• Amaç: Etkinlik uygulamasının kullanıcıyı tanıyabilmesi

Çözüm adımları:

1. Etkinlik uygulaması, kullanıcıdan sosyal platformda kimlik doğrulamasını ister. Uygulama kullanıcının parolasını kendi sistemine almak yerine, kimlik doğrulama görevini ilgili platforma yönlendirebilir.
2. Kullanıcı doğrulama işlemini sosyal platformda tamamlar. Bu aşamada kullanıcının hangi uygulamaya hangi erişim iznini verdiği önemlidir; izin kapsamı API'nin tasarımına bağlıdır.
3. Kullanılan protokole göre sosyal platform, kullanıcıyı uygulamaya geri yönlendirebilir ve bir geri dönüş (callback) adresine yetkilendirme kodu iletebilir. Etkinlik uygulaması bu kodu token endpoint'inde bir erişim belirteciyle değiştirebilir; ardından gerekirse kullanıcı bilgisi endpoint'inden izin verilen bilgileri alabilir. Doğrulama sonucu her zaman doğrudan bir API yanıtı olarak uygulamaya aktarılmaz.
4. Etkinlik uygulaması aldığı kodu, belirteci veya kullanıcı bilgisi yanıtını kontrol eder. Doğrulama başarılıysa oturum açma sürecini sürdürebilir; başarısızsa kullanıcıya girişin tamamlanmadığını bildirir.
5. Uygulama, aldığı bilgiyi yalnızca izin verilen amaçla kullanmalıdır. Kimlik doğrulama, bütün kullanıcı verilerine sınırsız erişim anlamına gelmez.

Sonuç: Burada API iki uygulamanın kimlik doğrulama sonucunu paylaşmasına aracılık eder. Fakat 'sosyal hesapla giriş' ile 'sosyal platformdaki her veriye erişim' aynı şey değildir. Yetkilendirme kapsamı ayrıca değerlendirilmelidir.

Kimlik doğrulama, yetkilendirme ve güvenlik sınırı

Kaynak makalede de vurgulandığı gibi API'ler erişimi kimlik doğrulama ve yetkilendirme mekanizmalarıyla sınırlandırabilir. Bu iki kavram birbirine yakın görünse de aynı soruyu cevaplamaz:

• Kimlik doğrulama, isteği yapan kişinin veya uygulamanın kim olduğunu kontrol eder.
• Yetkilendirme, doğrulanan tarafın hangi veriye veya işleve erişebileceğini belirler.

Örneğin bir kullanıcı sisteme giriş yapmış olabilir; ancak bu durum başka bir kullanıcının özel bilgilerini değiştirme yetkisine sahip olduğu anlamına gelmez. API tasarımında erişim kapsamı ayrıca tanımlanmalıdır.

Güvenlik yalnızca parola veya anahtar eklemekten ibaret değildir. İsteklerin hangi verileri taşıdığı, hassas bilgilerin nasıl korunduğu ve istemcinin hangi işlemleri yapabildiği de önemlidir. Veri aktarımında şifreleme kullanılması korumayı artırabilir; ancak şifreleme, hatalı yetki tasarımını tek başına düzeltmez.

API kullanıcısı açısından pratik karar kuralı şudur: Bir istek reddedildiğinde yalnızca 'API çalışmıyor' sonucuna varılmamalıdır. Kimlik doğrulama eksik olabilir, kullanıcıda ilgili yetki olmayabilir, istek biçimi hatalı olabilir veya servis geçici olarak kullanılamıyor olabilir. Hatanın nedeni, API'nin cevap yapısı ve dokümantasyonu üzerinden ayrıştırılmalıdır.

API türlerini değil, kullanım kapsamını karşılaştırmak

API'ler farklı ölçütlerle sınıflandırılabilir. Kaynakta yer alan örnekler, web siteleriyle sınırlı olmadığını; mobil uygulamalarda, masaüstü yazılımlarında, IoT cihazlarında, oyun konsollarında ve sunucular arası iletişimde de kullanılabildiğini gösterir.

Bir API'yi incelerken şu ayrımlar daha açıklayıcıdır:

• Dışa açık API: Başka geliştiricilerin kullanmasına belirli koşullarla izin verilen arayüzdür. Açık olması, sınırsız ve ücretsiz olduğu anlamına gelmez.
• Kurum içi API: Aynı kuruluşun farklı uygulamaları veya servisleri arasında kullanılabilir. Dışarıya kapalı olması, hiçbir güvenlik kuralına ihtiyaç duymadığı anlamına gelmez.
• Üçüncü taraf API: Harita, ödeme veya sosyal giriş gibi bir işlevi başka bir sağlayıcıdan almayı mümkün kılar.

Ücretsiz kullanım, sınırsız kullanım demek değildir. Kaynakta belirtildiği üzere bazı API'ler ücretsiz olabilir, bazıları belirli bir kullanım sınırına kadar ücretsiz sunulabilir, bazıları ise abonelik veya kullanım başına ücretlendirme uygulayabilir. Bu yüzden bir API seçerken fiyatlandırma kadar kullanım limiti, izin kapsamı, cevap biçimi ve servis sürekliliği de incelenmelidir.

API ile kütüphane de aynı kavram değildir. <slug: kutuphane-nedir> bir geliştiricinin kendi programına dahil ettiği yeniden kullanılabilir kodlar bütünüdür; API ise bir yazılımın sunduğu erişim kuralları ve arayüzdür. Bir kütüphane, bir API'yi kullanmayı kolaylaştırabilir; fakat bu iki terim birbirinin eş anlamlısı değildir. Benzer biçimde <slug: framework-nedir>, uygulamanın genel geliştirme yapısını belirleyen daha geniş bir çerçevedir.

Sık yapılan hatalar ve karıştırılan kavramlar

API konusunda en sık görülen yanlışlar şunlardır:

• 'API yalnızca web sitesidir' düşüncesi: API bir web sayfası değildir. Web tabanlı API'ler yaygın olsa da API yaklaşımı, farklı yazılımların iletişim kurduğu başka ortamlarda da kullanılabilir.
• 'API doğrudan veritabanıdır' düşüncesi: API, veritabanının kendisi değildir. Genellikle veriye veya işleme kontrollü bir giriş noktası sağlar. İstemcinin veritabanına doğrudan bağlanması, API ile aynı şey değildir.
• 'Açık API herkese sınırsız erişim verir' düşüncesi: Açık veya dış geliştiricilere sunulan bir API; kayıt, anahtar, kullanım limiti, izin veya ücret koşullarına sahip olabilir.
• 'Kimlik doğrulama varsa bütün işlemler yapılabilir' düşüncesi: Kimliği doğrulanan tarafın yetkileri sınırlı olabilir. Kimlik doğrulama ve yetkilendirme ayrı aşamalardır.
• 'Cevap geldiyse işlem başarılıdır' düşüncesi: Bir API cevap göndermiş olabilir; ancak cevap bir hata, eksik veri veya reddedilme bilgisi içerebilir. İstemci cevabın içeriğini ve durumunu değerlendirmelidir.
• 'API her zaman aynı kalır' düşüncesi: Servis sağlayıcılar endpoint, alan adı veya cevap yapısında değişiklik yapabilir. Bu nedenle sürümleme ve dokümantasyon takip edilmelidir.
• 'API kullanmak güvenliği otomatik çözer' düşüncesi: API kontrollü erişim sağlayabilir; fakat yanlış yetkilendirme, gereğinden fazla veri paylaşımı veya kötü tasarlanmış hata yönetimi güvenlik riski doğurabilir.

Sınır durumlarından biri de API ile entegrasyonun çalışmasına rağmen kullanıcı deneyiminin bozulmasıdır. Örneğin servis geç cevap veriyorsa uygulama sonsuza kadar beklememeli; veri biçimi değişmişse eski alan adını kullanarak yanlış sonuç üretmemelidir. Entegrasyonun başarısı, yalnızca ilk bağlantının kurulmasına değil, değişiklik ve hata durumlarının yönetilmesine de bağlıdır.