Telefonunuzda hava durumuna bakıyorsunuz. Ekranda bulunduğunuz şehrin sıcaklığı, yağmur ihtimali ve önümüzdeki günlerin tahmini görünüyor. Ardından bir alışveriş uygulaması açıyorsunuz. Ürünün stok durumunu kontrol ediyor, sipariş veriyor ve kargonuzun nerede olduğunu takip ediyorsunuz.
Biraz sonra harita uygulamasından yol tarifi alıyorsunuz. Uygulama trafik yoğunluğunu değerlendiriyor, alternatif yollar öneriyor ve tahmini varış saatini hesaplıyor.
Bütün bunları yaparken oldukça doğal görünen bir şey gerçekleşiyor: Telefonunuzdaki uygulamalar, ihtiyaç duydukları bilgilerin bir bölümünü kendi içlerinde üretmek yerine başka sistemlerden alıyor.
Hava durumu uygulaması meteorolojik verilerden yararlanıyor. Alışveriş uygulaması ürün ve sipariş kayıtlarıyla iletişim kuruyor. Harita uygulaması konum, yol ve trafik bilgilerini işliyor.
Bu sistemlerin birbirinden veri alabilmesi ve belirli işlemleri gerçekleştirebilmesi için ortak bir iletişim yöntemine ihtiyacı var.
İşte API, modern yazılım dünyasında bu iletişimin kurulmasını sağlayan en önemli araçlardan biri.
API kavramı genellikle programlama derslerinde karşımıza çıkar. Fakat etkisi yalnızca yazılımcılarla sınırlı değildir. Günlük hayatta kullandığımız mobil uygulamaların, web sitelerinin, ödeme sistemlerinin ve çevrim içi hizmetlerin arkasında API’ler bulunur.
Üstelik API yalnızca internetten bilgi çekmek için kullanılmaz. Bir programın işletim sisteminin özelliklerinden yararlanması veya başka bir yazılım bileşeniyle iletişim kurması da API aracılığıyla gerçekleşebilir.
Peki API tam olarak nedir? Bir uygulama başka bir uygulamadan nasıl bilgi ister? Bu iletişim sırasında hangi bilgiler gönderilir, kimlik nasıl doğrulanır ve sistemler birbirinin verilerine ne kadar erişebilir?
Bu soruların cevaplarını anlamak için önce oldukça önemli bir ayrımı öğrenmemiz gerekiyor.
Bir uygulamanın bütün işleri kendisinin yapmasıyla başka sistemlerden hizmet alması aynı şey değildir.
API nedir ve neden ihtiyaç duyulur?
API, İngilizce Application Programming Interface ifadesinin kısaltmasıdır. Türkçede Uygulama Programlama Arayüzü olarak adlandırılır.
En temel anlamıyla API, bir yazılımın başka bir yazılımın sunduğu belirli işlevleri veya verileri hangi kurallar çerçevesinde kullanabileceğini tanımlayan arayüzdür.
Bu tanım ilk bakışta biraz teknik gelebilir.
Bunu daha anlaşılır hâle getirmek için yeni bir mobil uygulama geliştirdiğimizi düşünelim.
Uygulamamız, kullanıcının bulunduğu şehrin hava durumunu gösterecek. Ancak dünyanın her yerindeki sıcaklıkları ölçen istasyonlarımız, uydu sistemlerimiz veya meteoroloji uzmanlarımız bulunmuyor.
Bütün bu altyapıyı sıfırdan kurmak oldukça pahalı ve gereksiz olurdu.
Bunun yerine meteorolojik veri sağlayan uygun bir hizmetten yararlanabiliriz.
Uygulamamız ilgili servise belirlenen kurallara uygun bir istek gönderir. Servis isteği değerlendirir ve kullanmamıza izin verilen verileri yanıt olarak iletir.
Uygulamamız da gelen bilgileri kullanıcının anlayacağı şekilde ekranda gösterir.
Burada iki farklı sistem bulunur: Biri hava durumunu göstermek isteyen uygulama, diğeri ise veriyi sağlayan hizmettir.
API, bu iki sistemin birbirinden ne isteyebileceğini ve nasıl iletişim kuracağını belirler.
Ancak API’yi yalnızca iki program arasında açılmış bir bağlantı olarak düşünmek eksik olur.
API aynı zamanda bir kullanım sözleşmesidir.
Hangi işlemler yapılabilir? Hangi bilgiler gönderilmelidir? Hangi sonuçlar alınabilir? Hangi işlemler için kimlik doğrulaması gerekir? Hatalar nasıl bildirilir?
İyi tasarlanmış bir API, bütün bu sorulara belirli ve tutarlı cevaplar verir.
Böylece bir uygulama başka bir sistemin iç yapısını ayrıntılı olarak bilmeden onun sunduğu özelliklerden yararlanabilir.
API, bir programın içini açmak anlamına gelmez
Burada önemli bir yanlış anlamayı düzeltelim.
Bir hizmet API sunduğunda başka geliştiricilere bütün sistemini açmış olmaz.
Bir bankanın API üzerinden bazı finansal işlemler sunması, herhangi bir uygulamanın bankanın veri tabanına doğrudan erişebileceği anlamına gelmez.
Benzer şekilde bir alışveriş sitesinin ürün bilgilerini API üzerinden sunması, o API’yi kullanan kişinin bütün müşteri kayıtlarını görebileceği anlamına gelmez.
API’nin temel amaçlarından biri, sistemin iç yapısıyla dışarıya sunulan işlevler arasında kontrollü bir sınır oluşturmaktır.
Örneğin bir kargo şirketinin sisteminde milyonlarca gönderi bulunabilir. Kargo takip hizmeti, izin verilen bir takip numarasına ilişkin durumu sorgulama işlevi sunabilir.
Bu işlevin var olması, sorguyu yapan herkesin bütün gönderileri listeleyebileceği anlamına gelmez.
Aynı şekilde bir uygulamanın kullanıcı profili görüntüleme özelliği bulunabilir. Ancak sunucunun, isteği yapan kişinin ilgili profile erişim hakkı olup olmadığını ayrıca değerlendirmesi gerekir.
Buradaki ayrım yazılım güvenliği açısından çok önemlidir.
Bir işlevin teknik olarak mevcut olması, herkesin o işlevi kullanma yetkisi bulunduğu anlamına gelmez.
API’ler doğru tasarlandığında geliştiricilerin işini kolaylaştırırken sistemin hangi özelliklerinin dışarıya açılacağını da kontrol altında tutmaya yardımcı olur.
Uygulamalar birbiriyle nasıl konuşur?
Şimdi günlük bir örnek üzerinden sürecin tamamını inceleyelim.
Hayalî bir ŞehirCep uygulaması geliştirdiğimizi düşünelim. Bu uygulama kullanıcıya hava durumunu, yakın çevresindeki bazı hizmetleri ve güncel bilgileri gösterecek.
Kullanıcı uygulamayı açtığında bulunduğu şehir için hava durumu bilgisi görmek istiyor.
Öncelikle uygulama hangi şehir için bilgi isteyeceğini belirlemelidir. Bu bilgi kullanıcı tarafından elle seçilmiş olabilir veya uygun izin verilmişse cihazın konumundan yararlanılarak elde edilebilir.
Ardından uygulama, meteorolojik veri sağlayan hizmetin API’sine bir istek gönderir.
İstek kabaca şunu söyler:
“Ankara için güncel sıcaklık ve hava durumu bilgisini istiyorum.”
Bu istek ağ üzerinden ilgili hizmete ulaşır.
Hizmet, gelen bilgileri değerlendirir. İstekte gerekli parametrelerin bulunup bulunmadığını kontrol eder. Kullanım kuralları gerektiriyorsa uygulamanın kimliğini veya erişim iznini doğrular.
Her şey uygunsa istenen veriyi hazırlar ve yanıt gönderir.
Uygulama gelen yanıtı işler. Örneğin sıcaklık değerini derece simgesiyle, hava durumunu uygun bir görselle ve açıklamayla kullanıcıya sunar.
Kullanıcı bütün bunların sonucunda yalnızca ekranda sıcaklığı görür.
Oysa arka planda ayrı görevler üstlenen sistemler birlikte çalışmıştır.
İstek ve yanıt mantığı
Birçok web API’sinin temelinde istek–yanıt, yani request–response modeli bulunur.
İsteği gönderen tarafa istemci (client), isteği karşılayan tarafa ise sunucu (server) denir.
İstemci her zaman bir web tarayıcısı değildir. Mobil uygulama, masaüstü programı veya başka bir sunucu da istemci rolünde bulunabilir.
İstemci, yapmak istediği işlemi belirten bir istek gönderir. Sunucu bu isteği işler ve uygun bir yanıt döndürür.
Yanıt her zaman istenen bilgi olmak zorunda değildir.
Başarılı bir işlem sonucu, hata açıklaması, erişim reddi veya yeniden deneme gerektiğini belirten bir durum da gönderilebilir.
Örneğin hava durumu hizmetine var olmayan bir şehir kodu gönderildiğinde sunucu geçersiz bilgiyle ilgili hata verebilir.
Servis geçici olarak kullanılamıyorsa farklı bir hata oluşabilir.
İstek sınırına ulaşıldıysa hizmet belirli bir süre beklenmesini isteyebilir.
Dolayısıyla uygulamaların konuşması yalnızca bilgi alışverişinden ibaret değildir.
İki sistem, isteğin sonucunu ve gerektiğinde başarısız olmasının nedenini de birbirine anlatmalıdır.
Görseldeki Ankara hava durumu ve API verileri temsili örnektir; gerçek zamanlı bir servisten alınmamıştır.
HTTP, API iletişiminde nasıl kullanılır?
İnternet üzerinden çalışan çok sayıda API, iletişim için HTTP protokolünden yararlanır.
HTTP, tarayıcıların web sunucularıyla iletişim kurmasında da kullanılan temel protokollerden biridir. API’ler bu altyapıyı yalnızca web sayfalarını almak için değil, yapılandırılmış verileri iletmek ve işlemleri başlatmak için de kullanabilir. Bu iletişimin web sayfaları açısından nasıl işlediğini bir web sitesinin açılış sürecini anlattığımız yazımızda inceleyebilirsiniz.
Ancak bütün API’lerin HTTP kullandığını düşünmemek gerekir. İşletim sistemi API’leri, kütüphane arayüzleri ve farklı iletişim protokolleriyle çalışan sistemler de vardır.
Web API’leri açısından HTTP’yi anlamak ise son derece yararlıdır.
Bir API isteğinde genellikle hangi adrese gidileceği, hangi işlemin yapılmak istendiği ve gerekiyorsa hangi bilgilerin gönderildiği belirtilir.
Örneğin tamamen örnek olması için oluşturduğumuz şu adresi düşünelim:
https://api.ornek.test/v1/hava?sehir=AnkaraBu adres gerçek bir hava durumu hizmeti değildir; yalnızca kavramları açıklamak için kullanıyoruz.
Buradaki api.ornek.test, hizmetin örnek alan adıdır.
/v1/hava bölümü istenen kaynağın yolunu gösterir.
sehir=Ankara ise sorguya eklenen bilgidir.
İstek bu adresin yanında bir HTTP yöntemi de içerir.
GET, POST ve diğer yöntemler ne anlama gelir?
Birçok API’de kullanılan başlıca HTTP yöntemleri şunlardır:
- GET: Bir kaynağın bilgisini istemek için kullanılır. Ürün listesi veya hava durumu verisi istemek buna örnek olabilir.
- POST: Sunucuya veri göndermek veya belirli bir işlemi başlatmak için kullanılır. Yeni sipariş oluşturmak buna örnektir.
- PUT: Belirlenen kaynağın temsilini oluşturmak veya değiştirmek için kullanılabilir.
- PATCH: Bir kaynağa kısmi değişiklik uygulamak için kullanılır.
- DELETE: Belirtilen kaynağın silinmesini istemek için kullanılır.
Bu yöntemlerin tanımlı anlamları vardır. Ancak belirli bir API’nin hangi işlemi hangi yöntemle sunduğunu öğrenmek için o API’nin belgelerine bakmak gerekir.
Örneğin POST her zaman yeni kayıt oluşturmak zorunda değildir. Bir sorgulamayı veya başka bir işlemi başlatmak için de kullanılabilir.
Aynı şekilde DELETE isteğinin başarılı olması, verinin fiziksel olarak ve geri alınamayacak şekilde silindiği anlamına gelmeyebilir. Bazı sistemler kayıtları mantıksal olarak pasif hâle getirebilir.
Buradaki önemli nokta yöntemlerin adını ezberlemek değil, API’nin hangi isteğe nasıl davranacağını öngörülebilir biçimde tanımlamasıdır.
HTTP’nin çalışma mantığı ve yöntemleri MDN HTTP belgelerinde ayrıntılı olarak açıklanıyor.
JSON nedir ve API’ler neden kullanır?
İstemci bir istekte bulundu. Sunucu da yanıt verdi.
Peki gelen veri uygulama tarafından nasıl anlaşılır?
Bunun için kullanılan yaygın biçimlerden biri JSON‘dur.
JSON, JavaScript Object Notation ifadesinin kısaltmasıdır. Verilerin anahtar ve değerler üzerinden düzenli biçimde temsil edilmesini sağlayan metin tabanlı bir formattır.
Adında JavaScript geçmesine rağmen yalnızca JavaScript programlarında kullanılmaz. Python, C#, Java, PHP ve başka birçok programlama dili JSON verilerini işleyebilir.
Az önceki örneğe dönelim.
Hava durumu hizmetinden şöyle bir yanıt geldiğini düşünelim:
{
"sehir": "Ankara",
"sicaklik": 21,
"durum": "Parçalı bulutlu"
}Bu tamamen temsili bir yanıttır; Ankara’nın gerçek zamanlı hava durumu bilgisi değildir.
Burada sehir, sicaklik ve durum alanları bulunuyor.
Uygulama bu alanları okuyarak uygun bilgileri ekranda gösterebilir.
Örneğin sicaklik alanındaki sayıyı alıp “21 °C” biçiminde gösterebilir. durum alanını kullanarak hava durumuna ilişkin açıklama sunabilir.
JSON’un yararı veriyi anlaşılır bir yapıya oturtmasıdır.
Ancak JSON tek başına bir API değildir. Yalnızca veriyi temsil etme biçimidir. Bir API JSON kullanabilir ama başka biçimler de kullanabilir.
Burada dikkat edilmesi gereken başka bir konu da verinin yapısının tutarlı olmasıdır.
Uygulama sicaklik adlı bir alan beklerken hizmet bunu habersizce temperatureValue olarak değiştirirse uygulamanın ilgili bölümü çalışmayabilir.
Benzer şekilde bir alan bazen sayı, bazen metin olarak geliyorsa geliştiricinin bu farklılıklara hazırlıklı olması gerekir.
Bu nedenle güvenilir API tasarımında yalnızca verinin gönderilmesi değil, verinin hangi yapıda gönderileceğinin açıkça tanımlanması da önemlidir.
JSON yapısını incelemek, hatalı biçimlendirmeyi fark etmek veya veriyi okunur hâle getirmek için PratikTekno’nun JSON Biçimlendirici ve Doğrulayıcı aracından yararlanabilirsiniz.
API ile veri tabanı aynı şey midir?
Bu konu özellikle programlamaya yeni başlayanların sık karıştırdığı ayrımlardan biridir.
API ve veri tabanı birbirinin yerine kullanılan iki farklı isim değildir.
Veri tabanı, bilgilerin belirli bir düzen içinde saklanmasını ve yönetilmesini sağlayan sistemdir.
API ise başka yazılım bileşenlerinin belirli verilere veya işlevlere nasıl erişeceğini tanımlayabilir.
Bir alışveriş uygulaması düşünelim.
Ürünler, stoklar, siparişler ve müşteri bilgileri bir veri tabanında tutuluyor olabilir.
Mobil uygulama ürün listesini göstermek istediğinde doğrudan veri tabanına bağlanmak yerine uygulamanın sunucu tarafındaki API’siyle iletişim kurabilir.
Sunucu gelen isteği değerlendirir, gerekli yetki kontrollerini yapar, veri tabanından uygun bilgileri alır ve yanıt oluşturur.
Ancak her API isteğinin veri tabanına ulaşması da şart değildir.
Bilgi önbellekten alınabilir, başka bir hizmetten getirilebilir veya hesaplanarak oluşturulabilir.
Örneğin iki şehir arasındaki mesafeyi hesaplayan bir API, bazı sonuçları çalışma sırasında hesaplayabilir.
Burada önemli olan sistemin içindeki bütün bileşenleri dışarıya açmak zorunda olmamasıdır.
API, verinin nerede saklandığından çok, ona hangi kurallarla erişilebildiğiyle ilgilidir.
Veri tabanlarının nasıl kurulduğunu ve yönetildiğini öğrenmek isteyenler için PostgreSQL 18 ve pgAdmin 4 Kurulumu rehberimiz bu yapının diğer tarafını anlamaya yardımcı olabilir.
Günlük hayatta API’lerle nerelerde karşılaşıyoruz?
API’ler yalnızca programcıların kullandığı özel araçlar değildir. Günlük hayatın birçok dijital hizmeti, farklı sistemlerin birlikte çalışmasına dayanır.
Harita ve konum hizmetlerinde bir uygulama, uygun bir harita sağlayıcısının sunduğu API üzerinden harita görüntüleme, adres arama veya rota hesaplama gibi işlevlerden yararlanabilir.
Bu sayede her uygulamanın dünyanın bütün yol ve adres verilerini kendisinin hazırlaması gerekmez.
Alışveriş uygulamalarında ürün bilgileri, stok kayıtları, sipariş durumu ve kargo hareketleri farklı sistemlerle paylaşılabilir.
Ancak her şirketin sistemleri aynı biçimde entegre ettiği varsayılmamalıdır. Bazı işlemler doğrudan kendi sunucusunda yürütülürken bazıları dış hizmetlere aktarılabilir.
Ödeme sistemlerinde mağaza uygulaması bir ödeme hizmetinin API’si üzerinden işlemi başlatabilir ve sonucunu öğrenebilir.
Bu iletişim, ödeme işleminin güvenli biçimde yürütülmesinin yalnızca bir parçasıdır. Kart bilgilerinin nasıl işlendiği, hangi tarafın hangi veriyi tuttuğu ve hangi güvenlik gerekliliklerinin uygulandığı kullanılan ödeme modeline bağlıdır.
Kargo takip sistemlerinde alışveriş sitesi, gönderi durumunu lojistik hizmetiyle yapılan bir entegrasyon üzerinden öğrenebilir.
Sosyal giriş sistemlerinde bazı uygulamalar kullanıcıya mevcut bir hesapla oturum açma seçeneği sunar. Bu tür entegrasyonlarda kimlik doğrulama ve yetki devri mekanizmaları devreye girebilir.
Yapay zekâ uygulamalarında bir geliştirici, kendi uygulamasının içinde çalıştırmadığı bir modele API üzerinden istek gönderip yanıt alabilir.
Bu örneklerde ortak olan şey, bir yazılımın başka bir sistemin sunduğu özelliği kullanmasıdır.
Ancak hiçbirinde “API var, bütün verilere erişilebilir” sonucu çıkarılamaz.
Her hizmetin erişim koşulları, izinleri, teknik sınırlamaları ve maliyetleri farklı olabilir.
API anahtarı, kullanıcı hesabı ve erişim izni arasındaki fark
Birçok hizmet, API’sini kullanan uygulamaların kimliğini veya kullanım hakkını belirlemek ister.
Bunun için API anahtarları, erişim belirteçleri veya farklı kimlik doğrulama yöntemleri kullanılabilir.
Ancak bu kavramların hepsi aynı anlama gelmez.
API anahtarı, bazı hizmetlerde isteğin hangi uygulama veya projeyle ilişkili olduğunu belirlemeye yarar. Kullanım kotası ve ücretlendirme gibi amaçlarla da kullanılabilir.
Fakat bir API anahtarının bulunması her zaman belirli bir kullanıcının kimliğinin doğrulandığı anlamına gelmez.
Örneğin uygulamamız bir hava durumu hizmetini kullanmak için proje adına verilmiş bir API anahtarı taşıyabilir. Bu anahtar, uygulamayı kullanan kişilerin her birini ayrı ayrı temsil etmek zorunda değildir.
Buna karşılık kullanıcıya özel verilere erişen sistemler daha farklı mekanizmalara ihtiyaç duyabilir.
Bu noktada iki kavramı ayırmak gerekiyor.
Kimlik doğrulama ile yetkilendirme aynı şey değildir
Kimlik doğrulama, isteği yapan kişinin veya sistemin kim olduğunu belirlemeye çalışır.
Yetkilendirme ise kimliği bilinen kişinin hangi işlemleri yapabileceğine karar verir.
Bir şirkette çalışan iki kişinin sisteme başarıyla giriş yaptığını düşünelim.
İkisinin de kimliği doğrulanmış olabilir.
Ancak bir çalışan yalnızca kendisine verilen görevleri görüntüleyebilirken yönetici daha geniş yetkilere sahip olabilir.
Bu fark yetkilendirme ile ilgilidir.
Aynı mantık API’lerde de geçerlidir.
Bir kullanıcının geçerli oturumla sisteme bağlanması, başka bir kullanıcının özel kayıtlarını okuma hakkı bulunduğunu göstermez.
Bu nedenle sunucu, gerektiğinde yalnızca giriş yapılıp yapılmadığını değil, istenen kaynağa erişim iznini de kontrol etmelidir.
OWASP’ın API Security Top 10 çalışması, nesne düzeyinde yetkilendirme hatalarını önemli API güvenlik riskleri arasında ele alıyor.
Örneğin kullanıcı kendi siparişini görüntüleyebiliyor diye URL’deki sipariş numarasını değiştirerek başka kişilerin siparişlerine erişebilmemelidir.
Bu kontrol yalnızca ekrandaki düğmelerin gizlenmesiyle sağlanamaz. Yetkilendirme sunucu tarafında uygulanmalıdır.
API anahtarları neden dikkatli korunmalıdır?
Bazı API anahtarları ve erişim belirteçleri gizli bilgiler olarak değerlendirilmelidir.
Gizli bir anahtarı herkese açık kaynak koduna eklemek, yanlış kişilerin bu anahtarı kullanmasına yol açabilir.
Bu durum yetkisiz erişim, kota tüketimi veya beklenmedik ücretlendirmeler oluşturabilir.
Bu nedenle gizli nitelikteki kimlik bilgileri güvenli ortamda saklanmalı; mümkün olduğunda erişim yetkileri sınırlandırılmalıdır.
Ancak bütün API anahtarlarının aynı gizlilik modeline sahip olmadığını da bilmek gerekir. Bazı hizmetler tarayıcı veya mobil uygulamada kullanılan, alan adı ya da uygulama kimliğiyle sınırlandırılmış anahtar modelleri sunabilir.
Doğru yaklaşım, hizmet sağlayıcının güvenlik ve kimlik doğrulama belgelerini esas almaktır.
Google Cloud’un API anahtarları için güvenlik önerileri bu konuda yararlı bir teknik kaynaktır.
Buradan çıkarılacak temel ders açık:
Bir API’nin çalışıyor olması, güvenli tasarlandığı anlamına gelmez.
Güvenlik, iletişim kurulmaya başlamadan önce düşünülmesi gereken bir tasarım kararıdır.
Bir API neden bazen cevap vermez?
Uygulama geliştiren herkesin öğrenmesi gereken önemli gerçeklerden biri şudur: Ağ üzerinden yapılan bir isteğin her zaman başarıyla tamamlanacağı varsayılamaz.
Bağlantı kopabilir.
Sunucu bakımda olabilir.
İstek hatalı hazırlanmış olabilir.
Kullanıcının erişim izni bulunmayabilir.
Hizmet kullanım sınırına ulaşmış olabilir.
Bu nedenle iyi bir uygulama yalnızca başarılı yanıt geldiğinde ne yapacağını değil, başarısız bir durumda nasıl davranacağını da bilmelidir.
HTTP üzerinden çalışan API’lerde yanıtın durumunu belirten kodlar önemli bir rol oynar.
Örneğin 200 başarılı bir isteği, 201 uygun durumlarda yeni bir kaynağın oluşturulduğunu gösterebilir.
400 hatalı istekle, 401 geçerli kimlik doğrulama bilgilerinin bulunmamasıyla ilişkili olabilir.
403, sunucunun isteği yerine getirmeyi reddettiğini belirtir.
404, istenen kaynağın bulunamadığını gösterebilir.
429, çok fazla istek gönderildiğini anlatır.
500, sunucu tarafında beklenmeyen bir hata oluştuğunda kullanılabilir.
503 ise hizmetin geçici olarak kullanılamadığını belirtebilir.
Ancak yalnızca durum koduna bakarak olayın bütün nedenini öğrenemeyiz. Yanıt içeriği, sunucu kayıtları ve isteğin bağlamı da değerlidir.
Örneğin 429 hatası alan bir uygulamanın hemen yüzlerce yeni istek göndermesi sorunu daha kötü hâle getirebilir.
Benzer şekilde ödeme oluşturma isteği sırasında bağlantı koptuysa işlemin sunucuda gerçekleşip gerçekleşmediği belirsiz kalabilir.
Bu durumda uygulamanın aynı ödeme isteğini düşünmeden tekrar göndermesi, uygun korumalar bulunmadığında birden fazla işleme yol açabilir.
Bu yüzden gerçek sistemlerde yeniden deneme kuralları, işlem kimlikleri ve aynı isteğin tekrarlanmasına karşı alınan önlemler önemlidir.
İyi bir uygulama hata karşısında nasıl davranır?
Kullanıcıya yalnızca “Bir hata oluştu” demek çoğu zaman yeterli değildir.
Örneğin hava durumu hizmeti geçici olarak çalışmıyorsa uygulama son alınan veriyi gösterebilir. Ancak bu verinin güncel olmadığı açıkça belirtilmelidir.
Ödeme sonucundan emin olunamıyorsa kullanıcıyı yeniden ödeme yapmaya zorlamak yerine işlemin durumu güvenli bir yöntemle sorgulanabilir.
Yetki süresi dolmuşsa uygulama uygun bir kimlik doğrulama süreci başlatabilir.
Burada en önemli ilke, hatayı kullanıcıdan gizlemek değil, hatanın etkisini kontrollü ve anlaşılır biçimde yönetmektir.
Bu yaklaşım yalnızca API’ler için değil, güvenilir yazılım geliştirmenin tamamı için geçerlidir.
REST API, GraphQL ve webhook aynı şey midir?
API kavramını araştırmaya başladığımızda kısa süre içinde REST, GraphQL ve webhook gibi terimlerle karşılaşırız.
Bunlar birbiriyle ilişkili olsa da aynı şeyi ifade etmez.
REST, web üzerinde kaynakları belirli ilkeler doğrultusunda ele alan mimari bir yaklaşımdır.
REST tarzında tasarlanmış HTTP API’lerinde kaynakları temsil eden adresler ve HTTP yöntemleri sık kullanılır.
Örneğin bir ürünün bilgilerini almak, ürün listesini görmek veya bir kaydı güncellemek için ilgili kaynaklara yönelik istekler oluşturulabilir.
Ancak HTTP kullanan veya JSON döndüren her API otomatik olarak REST ilkelerine tam olarak uyuyor sayılmaz.
GraphQL ise istemcinin ihtiyaç duyduğu alanları bir sorgu aracılığıyla belirlemesine imkân veren bir API sorgulama dili ve yürütme yaklaşımıdır.
Örneğin bir uygulama ürünün yalnızca adını ve fiyatını istiyorsa uygun tasarlanmış bir GraphQL API’sinde bu alanları seçebilir.
Bu esneklik bazı senaryolarda yararlıdır. Fakat GraphQL’in her durumda REST’ten daha hızlı veya daha güvenli olduğunu söylemek doğru değildir. Performans; sorguların yapısına, sunucu uygulamasına, önbelleğe ve veri kaynaklarına bağlıdır.
GraphQL’in sorgu yapısı resmî GraphQL belgelerinde açıklanıyor.
Webhook ise belirli bir olay gerçekleştiğinde başka bir sisteme otomatik bildirim gönderilmesi için kullanılan bir entegrasyon yaklaşımıdır.
Örneğin bir ödeme sağlayıcısı, ödeme durumu değiştiğinde işletmenin sunucusuna webhook gönderebilir.
Böylece işletmenin uygulaması her saniye ödeme durumunu sorgulamak zorunda kalmayabilir.
Ancak webhook’ların güvenli biçimde doğrulanması ve tekrarlanan bildirimlerin düzgün işlenmesi gerekir. Bir bildirimin iki kez ulaşması aynı işlemin iki kez yapılmasına neden olmamalıdır.
Özetle REST ve GraphQL, API’nin nasıl sunulabileceğiyle; webhook ise sistemler arasında olayların nasıl bildirilebileceğiyle ilgilidir.
WordPress’in bile API’si var mı?
Evet. Üstelik bu, API kavramını somutlaştırmak için oldukça iyi bir örnek.
WordPress yalnızca tarayıcıda görünen yazı ve sayfalardan oluşmaz. WordPress REST API üzerinden içeriklerle ve çeşitli sistem özellikleriyle programlı biçimde etkileşim kurulabilir.
Örneğin bir WordPress sitesinde uygun yapılandırma varsa şu yol kullanılarak yayımlanmış yazıların belirli bilgileri istenebilir:
/wp-json/wp/v2/posts
Buradaki adres, WordPress REST API’nin yazılarla ilgili kaynak yolunu temsil eder.
Bir uygulama bu API üzerinden herkese açık yazıların başlıklarını, özetlerini veya diğer sunulan bilgilerini alabilir.
Bu veriler farklı bir mobil uygulamada, özel bir ön yüzde veya başka bir sistemde gösterilebilir.
Ancak yazı oluşturma, düzenleme veya silme gibi işlemler için uygun kimlik doğrulama ve yetki kontrolleri gerekir.
Bütün WordPress verilerinin herkese açık olduğu düşünülmemelidir.
WordPress’in bu yapısı resmî REST API geliştirici belgelerinde açıklanıyor.
Buradaki ilginç nokta şudur:
Bir WordPress sitesini tarayıcıdan ziyaret eden kullanıcıyla WordPress API’sinden veri isteyen bir program, aynı içerik sisteminden farklı biçimlerde yararlanabilir.
Birinde tema aracılığıyla hazırlanmış bir web sayfası görürüz.
Diğerinde uygulamanın işleyebileceği yapılandırılmış veriler alabiliriz.
Aynı içerik, farklı arayüzler üzerinden kullanılabilir.
API kavramının yazılım geliştirmede bu kadar önemli olmasının nedenlerinden biri de budur.
Bir programcı kendi API’sini nasıl geliştirir?
API’ler yalnızca büyük teknoloji şirketlerinin hazırladığı hizmetler değildir.
Küçük bir yazılım projesinde de API geliştirmek mümkündür.
Örneğin bir görev takip uygulaması oluşturduğumuzu düşünelim.
Uygulamada görevler, kullanıcılar, tamamlanma durumları ve tarihler bulunuyor.
Görevleri gösteren bir web arayüzümüz ve aynı bilgileri kullanacak bir mobil uygulamamız olsun.
Bu iki arayüzün veri ve işlem kurallarını ayrı ayrı yazmak yerine ortak bir sunucu uygulaması hazırlayabiliriz.
Sunucu, görevleri listeleme, yeni görev oluşturma, görev durumunu güncelleme ve uygun yetkiyle kayıtları silme gibi işlevler sunabilir.
Web ve mobil uygulamalar bu işlevlerden API üzerinden yararlanabilir.
Böylece iş kuralları belirli bir yerde yönetilebilir.
Ancak ortak API kullanmanın bütün kod tekrarlarını otomatik olarak ortadan kaldıracağını düşünmemek gerekir. Kullanıcı arayüzüne ve platforma özel farklı kodlar yine bulunacaktır.
Bir API tasarlayan geliştiricinin yanıtlaması gereken sorular vardır:
Hangi kaynaklar sunulacak? İsteklerde hangi bilgiler zorunlu olacak? Hatalar nasıl bildirilecek? Kullanıcı izinleri nasıl kontrol edilecek? Veriler nasıl doğrulanacak? API değiştiğinde eski uygulamalar nasıl etkilenecek?
İyi tasarım, yalnızca çalışır durumda bir adres oluşturmak değildir.
Örneğin ilk sürümde ürün fiyatı metin olarak gönderiliyor, sonraki sürümde sayı olarak döndürülüyorsa istemci uygulamaların bu değişimden etkilenme ihtimali vardır.
Bu nedenle API sürümleme ve geriye dönük uyumluluk planlaması önemlidir.
Aynı şekilde API belgeleri de geliştirme sürecinin bir parçasıdır.
Bir geliştirici hangi adrese hangi isteği göndereceğini, hangi parametreleri kullanacağını ve nasıl yanıt bekleyeceğini bilmelidir.
OpenAPI gibi standartlar, HTTP API’lerinin sunduğu işlevlerin makineler ve geliştiriciler tarafından anlaşılabilecek biçimde tanımlanmasına yardımcı olur.
Programlamaya yeni başlayacaklar için Visual Studio Code’da Python Kurulumu ve İlk Program rehberimiz, uygulama geliştirmenin temel adımlarını öğrenmek açısından bir başlangıç olabilir.
API geliştirmek daha ileri bir aşamadır; fakat temel programlama mantığı öğrenildiğinde istek, veri ve yanıt ilişkisi çok daha anlaşılır hâle gelir.
Bir uygulama ne zaman kendi API’sini kullanmalı, ne zaman dışarıdan hizmet almalı?
Yazılım geliştirmede karşılaşılan önemli kararlardan biri budur.
Her işlevi sıfırdan geliştirmek hem maliyetli hem de zaman alıcı olabilir.
Örneğin bir uygulamanın temel amacı etkinlik planlamaksa dünyanın bütün hava durumu verilerini toplamak için ayrı bir sistem kurmak gerekli olmayabilir.
Uygun bir dış hizmetten veri almak daha mantıklı olabilir.
Buna karşılık uygulamanın kullanıcı hesapları, özel görev kayıtları ve kendine özgü iş kuralları varsa bu bölümleri kendi sunucu altyapısıyla yönetmesi gerekebilir.
Ancak dış API kullanmanın da bedelleri vardır.
Hizmet ücretli olabilir.
Belirli kullanım kotaları bulunabilir.
Servis geçici olarak çalışmayabilir.
Gelecekte fiyatlandırma veya kullanım koşulları değişebilir.
API’nin sunduğu bazı işlevler kaldırılabilir.
Ayrıca kullanıcı verilerinin başka bir hizmete aktarılması gizlilik ve mevzuat açısından değerlendirme gerektirebilir.
Bu yüzden bir entegrasyon kararı yalnızca “API var, kolayca bağlanırız” düşüncesiyle verilmemelidir.
İyi bir yazılım mimarisinde şu sorular önemlidir:
Hizmet kullanılamazsa uygulama ne yapacak?
Veriler geç gelirse kullanıcı ne görecek?
API beklenmedik yanıt döndürürse sistem nasıl davranacak?
Kullanım arttığında maliyet nasıl değişecek?
Hizmeti değiştirmek gerekirse hangi bileşenler etkilenecek?
Bu sorulara baştan cevap vermek, uygulama büyüdüğünde ortaya çıkabilecek sorunları azaltır.
API entegrasyonu, başka bir sistemin sunduğu gücü kullanmak kadar o sisteme olan bağımlılığı yönetmeyi de gerektirir.
API’ler yazılım dünyasını neden değiştirdi?
Geçmişte farklı yazılım sistemlerinin birbirleriyle iletişim kurması çoğu zaman çok daha fazla özel geliştirme gerektirebiliyordu.
Her sistemin kendi veri biçimi, bağlantı yöntemi ve kullanım kuralları bulunabiliyordu.
Standartlaşmış web teknolojileri ve daha tutarlı API tasarımları, farklı platformların birlikte çalışmasını kolaylaştırdı.
Bugün bir web uygulaması farklı hizmetlerden veri alabilir. Aynı sunucu hem Android hem iOS uygulamasına hizmet verebilir. Bir şirketin muhasebe, stok ve sipariş sistemleri belirlenen entegrasyon kurallarıyla bilgi paylaşabilir.
Bu yaklaşım yazılım geliştirmede önemli bir esneklik sağlar.
Bir uygulamanın kullanıcı arayüzü değişebilir ama uygun tasarlanmış bir API sayesinde arka plandaki bazı hizmetler kullanılmaya devam edebilir.
Başka bir ekip aynı API’yi kullanarak farklı bir istemci geliştirebilir.
Bir şirket yeni bir hizmet sağlayıcıya geçerken entegrasyonun belirli bölümlerini yeniden düzenleyebilir.
Elbette bütün bunlar kendiliğinden gerçekleşmez. İyi dokümantasyon, kararlı veri yapıları, güvenli erişim ve değişikliklerin dikkatli yönetilmesi gerekir.
Fakat API yaklaşımının sağladığı temel avantaj açıktır:
Yazılımların birbirinin iç yapısını kopyalamadan birlikte çalışabilmesini sağlar.
Bu sayede geliştiriciler her özelliği baştan inşa etmek yerine mevcut yetenekleri bir araya getirerek yeni hizmetler oluşturabilir.
API’lerin modern yazılım dünyasındaki değeri yalnızca veri taşımalarından değil, farklı sistemler arasında yeniden kullanılabilir işlevler sunmalarından gelir.
Kısaca
API, bir yazılımın başka bir yazılımın sunduğu işlevleri veya verileri belirli kurallar çerçevesinde kullanmasını sağlayan arayüzdür.
Mobil uygulamalar, web siteleri, masaüstü programları ve sunucu sistemleri API’ler aracılığıyla iletişim kurabilir.
Web API’lerinde bu iletişim çoğu zaman HTTP istekleri ve yanıtları üzerinden gerçekleşir. JSON gibi biçimler verilerin yapılandırılmış şekilde aktarılmasına yardımcı olur.
Ancak API yalnızca internetten veri almak anlamına gelmez.
Bir işlem başlatmak, kayıt oluşturmak, bilgi güncellemek veya başka bir sistemin belirli bir yeteneğini kullanmak da API aracılığıyla mümkün olabilir.
API’lerin güvenli ve güvenilir olması için kimlik doğrulama, yetkilendirme, veri doğrulama, hata yönetimi ve kullanım sınırları gibi konuların doğru tasarlanması gerekir.
Bir API’nin bulunması, bütün bilgilere sınırsız erişim sağlandığı anlamına gelmez.
Aynı şekilde API kullanmak, uygulamanın her zaman sorunsuz çalışacağını garanti etmez. Ağ bağlantısı, hizmet kesintileri, uyumluluk ve dış sistemlere bağımlılık gibi koşullar da değerlendirilmelidir.
Bugün kullandığımız çok sayıda dijital hizmetin arkasında farklı yazılımların birlikte çalışması bulunuyor.
Bir harita uygulamasından rota almak, çevrim içi alışverişte sipariş durumunu görüntülemek veya bir mobil uygulamada güncel bilgilere ulaşmak bu iş birliğinin günlük örnekleridir.
Ve API kavramının özünü tek bir düşünceyle açıklayabiliriz:
Bir uygulamanın her şeyi bilmesi veya her şeyi kendisinin yapması gerekmez. Önemli olan, başka bir sistemden ne isteyebileceğini ve aldığı yanıtı nasıl kullanacağını bilmesidir.
API’ler işte bu iletişimi mümkün kılan kuralları oluşturur.
Yazılım dünyasında gerçek güç çoğu zaman tek bir programın yapabildiklerinde değil, farklı programların güvenli ve anlamlı biçimde birlikte yapabildiklerinde ortaya çıkar.
Yeni rehberleri kaçırmayın
Yeni teknoloji rehberleri ve pratik çözümler e-postanıza gelsin.
