API nedir: kayda ikinci bir program dokunduğunda

API, bir programın başka bir programa verdiği yazılı sözdür: şu adrese şu adlarla sorarsan karşılığında şunu alırsın. Böyle bir söze ihtiyaç olup olmadığına teknoloji tercihi değil, aynı kayda uygulamanızın dışından hangi programın dokunacağı karar veriyor. Tahlil.com’da hastanın telefonundaki uygulama, değerlerin girildiği web sitesinden ayrı çalışan bir program ve aynı kayda bakıyor.

API nedir, açılımı ne, ne işe yarar

Açılımı uygulama programlama arayüzü. Buradaki arayüz bir ekran değil, iki programın buluştuğu yer. Yazılımcınız “buna bir API yazmamız gerekecek” dediğinde size bir teknoloji sormuyor, bir kayıt sorusu soruyor.

Söz, karşı tarafın neyi garanti ettiğini yazıya döküyor. Yazılan şeyler belli: sorunun gideceği adres, sorarken kullanılacak alan adları, geri dönecek cevabın biçimi. Bunlar baştan sabitlendiği için çağıran program her seferinde aynı yere aynı dille soruyor ve aynı yapıda cevap alıyor.

“Arayüz” kelimesi burada yanlış bir resim çiziyor. Okur arayüz duyunca ekran düşünüyor; oysa bu arayüzün görseli yok. Kullanıcı ekranı görüyor, API ekranın arkasındaki konuşmayı taşıyor. Bir uygulamada düğmeye bastığınızda ekran size bir sonuç gösteriyor, ama o sonucu getiren konuşma iki program arasında geçiyor ve o konuşmayı hiç görmüyorsunuz.

Bu yüzden API’nin kullanıcısı insan değil. Kimse bir API’yi açıp içinde dolaşmıyor. Onu kullanan taraf, sizin ya da başkasının yazdığı başka bir program. İşletme sahibi için pratik karşılığı şu: API bir ekran talebi değil, bir bağlantı talebi. Kapsamı da ekran sayısıyla değil, kayda bağlanan program sayısıyla konuşuluyor.

Sözün ne işe yaradığı da burada görünüyor. Yazılı bir söz olmadan ayrı çalışan iki programın ortak bir kayıt üzerinde buluşması, her değişiklikte ikisini birlikte elden geçirmek demek. Söz yazıldığında taraflardan biri kendi içinde değişebiliyor ve karşı tarafa haber vermesi gerekmiyor. Haber vermeyi gerektiren tek durum, sözün kendisinin değişmesi.

Kazancın işletme tarafındaki karşılığı da şu. Kayda yeni bir yüzey eklemek sözü yeniden yazmayı gerektirmiyor; yeni gelen program aynı adlarla aynı kapıya soruyor. Söz olmasaydı her yeni yüzey kaydın içine kendi yolunu açardı ve o yollardan hangisinin doğru veriyi getirdiğini kimse söyleyemezdi.

Son bir ayrım gerekiyor. Aynı kısaltma yazılım dışındaki alanlarda başka şeyleri adlandırıyor; ilaç ve havacılık literatüründe karşılığı bambaşka. Bu yazının konusu yazılımdaki karşılığı, yani programlar arasındaki söz.

Bir çağrıda ne gidiyor, ne geliyor

Mekanizmanın en kısa hâli şöyle işliyor. Çağıran program sabit bir adrese gidiyor, adı belli alanları dolduruyor ve bir istek bırakıyor. Karşı taraf isteği alıyor, kendi tarafındaki işi yapıyor ve aynı adlarla bir cevap döndürüyor. Gidenin ve gelenin adları baştan yazılı olduğu için iki taraf da ne bekleyeceğini biliyor.

Bu düzenin asıl kazancı sırada: çağıran taraf karşı tarafın içini bilmek zorunda değil. Bildiği tek şey hangi adla ne soracağı ve karşılığında ne alacağı. Kapının arkasındaki iş baştan sona değişse de, adlar ve cevabın biçimi yerinde kaldığı sürece çağıran programa dokunulmuyor. Okur için karşılığı somut: bir tarafta yapılan iyileştirme öteki tarafta bir geliştirme kalemi doğurmuyor.

Çağrıyı kimin başlattığı da sözün parçası. Bir tarafta bekleyen kapı var, öteki tarafta o kapıyı çalan program. Bekleyen taraf kendiliğinden konuşmuyor, sorulmadıkça sessiz duruyor. Bu ayrım kapsam konuşmasında işe yarıyor, çünkü hangi tarafın yazılacağını belirliyor: kapıyı mı açıyorsunuz, kapıyı çalan programı mı yazdırıyorsunuz?

Teklifinizde “REST API” yazıyorsa ikinci bir kalem satın almıyorsunuz. REST, bu sözün yazılma biçimlerinden birinin adı: adresin nasıl kurulacağı, isteğin nasıl gönderileceği ve cevabın nasıl düzenleneceği belirli kurallara bağlanıyor. Kapının kendisi yine API olarak duruyor; söylenen şey, o kapının hangi düzene göre yazılacağı. Teklifte iki ayrı satır gibi görünen şey çoğu zaman aynı işin adı ile biçimi.

“API entegrasyonu” da ayrı bir teknoloji değil. İki programı bu kapıdan bağlama işinin gündelik adı. İsteğin içeriği teknolojiyle değil kayıtla ilgili: hangi kayıt hangi programa açılacak, çağrıyı kim başlatacak, hangi alanlar geçecek. Bu sorular cevaplandığında kapsam da fiyat da konuşulabilir hâle geliyor; cevaplanmadığında istek tarifsiz kalıyor. Belirli bir dış sistemin nasıl bağlandığı ayrı bir konu: defteri başkası tutuyorsa isteğin neye dönüştüğünü muhasebe programıyla kurulan teslim noktası üzerine ayrıca yazdık.

Bir de kapının hiç kurulmadığı durum var. Ortada ayrı çalışan ikinci bir program yoksa aralarında çağrı geçmiyor, dolayısıyla anlaşılacak bir ad listesi de doğmuyor. O durumun kendi örneği yazının sonunda.

Kapıyı açtıran şey teknoloji seçimi değil, kayda dokunan ikinci program

Soru çoğu zaman yanlış yerden sorulur. “Kaç ekranımız olacak” sorusunun cevabı bir API gerekip gerekmediğini söylemiyor. Söyleyen soru şu: bu kayda benim uygulamamın dışından hangi program dokunacak? Bu soruyu teknoloji bilmeden de cevaplayabilirsiniz, çünkü cevabı ekranlarda değil işin akışında duruyor.

Soruyu kendi işinize uygulamak için teknik bir terim gerekmiyor. Kaydı adlandırın: müşteri, cihaz, sipariş, randevu. Sonra o kaydın yanına gelen programları sayın: panelden giren personel bir program kullanıyor, sahadaki ekip ikinci bir programla geliyor, dışarıdaki bir servis de kendi programıyla geliyor. Listede uygulamanızın dışından gelen bir satır varsa kapı gündeme girmiş demektir.

Hastanın girdiği tahlil değerlerinin hekim denetiminden geçtiği platformda mekanizma net görünüyor. Değerler web sitesinden giriliyor, yorum hekim panelinde yazılıyor ve onaylanıyor. Telefondaki uygulama ise bu ikisinin koştuğu yerde değil, hastanın kendi cihazında çalışıyor; yine de baktığı kayıt aynı kayıt. O cihaz işletmenin işlettiği bir donanım değil; ne zaman açılacağını kullanıcının kendisi belirliyor.

Ofisteki müşteri ve cihaz kaydıyla sahadaki teknisyenin buluştuğu kendi ürünümüzde aynı ayrım ofisle saha arasında duruyor. Saha uygulaması teknisyenin telefonunda, ofis paneli web tarafında çalışıyor. İkisi de aynı müşteri ve cihaz kaydına bakıyor; ayrı defter tutmuyorlar. Teknisyen kazan dairesinde servis kaydını açtığında, o kaydın gideceği yer ofisin okuduğu kaydın kendisi.

İki işte de kapıyı zorunlu kılan şey sahiplik değil. Telefondaki program bizim olabilir, hatta ürünün tamamı bizim olabilir. Zorunlu kılan şey, programın ayrı bir yerde ayrı çalışması. Ayrı çalışan iki tarafın ortak bir kayıt üzerinde buluşması için aralarında yazılı bir söz gerekiyor; sözsüz buluşma, her sürümde ikisini birlikte değiştirmek anlamına geliyor.

Buradan bir sınır çıkıyor. Uygulamanın hangi cihazda açılacağı, mağazaya mı çıkacağı ve bağlantı koptuğunda ne olacağı bu yazının konusu değil; o kararlar mobil uygulama tarafında veriliyor. Burada anlatılan şey kapının kendisi.

Karşı durumu da söylemek gerekiyor. Kayda tek bir program dokunuyorsa kapı kurmak karşılıksız bir maliyet olarak kalıyor. Kaç yüzeyin aynı çekirdeği dinleyeceği ve bu kararın hangi anda verildiği ise ayrı bir tartışma; onu geri alınması pahalı kararların neden koddan önce kapandığı üzerine yazmıştık.

Kapıdan yalnız dışarı değil içeri de geçiliyor

Kapı kelimesi tek yönlü bir boru çağrıştırıyor: içerideki kayıt dışarıya veriliyor. Gerçekte trafik iki yönde akıyor ve bunun için ikinci bir kapı kurulmuyor.

AlgoKlima’da bunun en günlük hâli iş dağıtımında görünüyor. Hangi işin hangi teknisyene gittiği ofis tarafında kararlaştırılıyor ve aynı müşteri ve cihaz kaydının üstüne yazılıyor. Sahadaki uygulama o atamayı aynı kayıttan okuyor. Yani kapıdan geçen ilk şey sahadan gelen veri değil, ofisten sahaya giden iş.

Bunun sahadaki karşılığı somut. Teknisyen sabah hangi işin kendisine düştüğünü telefon açarak öğrenmiyor; uygulama o atamayı kayıttan okuyup gösteriyor. Ofis tarafı da aynı kaydı değiştirerek işi devrediyor. Atama ayrı bir mesaj kanalında dursaydı, kaydın kendisi kime atandığını taşımaz ve iki taraf farklı şey okuyabilirdi.

Dönüş yönü de aynı kayda iniyor. Teknisyen servis kaydını açıyor, yaptığı işi yazıyor ve kapatıyor; yazdığı şey ofisin okuduğu kaydın kendisi oluyor. Garanti ve bakım geçmişi cihazın altında biriktiği için aynı adreste duran cihazların dosyaları birbirine karışmıyor. İki yön tek kaydın üstünde buluşuyor ve arada ikinci bir kopya tutulmuyor.

Tek kayıtta kalmanın bedeli de var, kazancı da. İki ayrı kopya tutulsa, hangisinin geçerli sayıldığını söyleyen kuralı sonradan birinin yazması gerekirdi. Tek kayıt bu soruyu doğurmuyor; onun yerine aynı kaydın iki yerden değiştirilebilmesi sorusunu doğuruyor ve o soru kapının tasarımına giriyor.

Tahlil platformunda aynı kayıt bir yüzeyden yazılıyor, başka bir yüzeyden okunuyor. Değer web sitesinden kayda giriyor, yorum hekim panelinde yazılıp onaylanıyor; telefondaki uygulama ise yorum hazır olduğunda hastaya haber veriyor ve metni aynı kayıttan okuyor. Ayrı bir kopya tutulsaydı, panelde onaylanan yorumun uygulamada görünen yorumla aynı olduğunu kimse garanti edemezdi.

Bu bölümün anlatmadığı bir şey var. Bağlantı yokken kaydın telefonda tutulması, bağlantı dönünce sıraya girmesi ve çakışan değişikliklerin nasıl kapandığı ayrı bir mekanizma; onu saha kaydının bağlantı olmadan nerede doğduğu üzerine yazdığımız sayfada açtık. Buradaki konu kapının kendisi: kaydın iki yönde de aynı yerden geçmesi.

Kapının karşı tarafı sizin mi, başkasının mı

İşletme sahibinin asıl sorusu bir kontrol sorusu: bu kapıyı ben mi açıyorum, yoksa başkasının kapısından mı geçiyorum? İkisi ayrı durum ve sonradan değiştirebileceğiniz şeyler farklı.

Ayrımın kanıtı tek çatının içinde duruyor. Optik formdaki işaretlemeleri form görüntüsünden okuyan araçta okuma servisi kendi tarafımızda. Servis ayrı bir çalışma zamanında duruyor, çağrı bizim tarafımızdan gidiyor ve sonuç platformun kendi sınav kaydına yazılıyor. Kapının iki yanını da biz yazdığımız için bir ad değişikliği tek masada kararlaştırılıyor.

Soru kitapçığını tek tek soruya ayıran araçta durum tersine dönüyor. Cevabı ilgili soruya bağlama işini dış model sağlayıcılarının kapısı yapıyor. Orada kapıyı biz açmıyoruz, kapıdan biz geçiyoruz. Adları ve cevabın biçimini karşı taraf koyuyor; bize düşen iş, dönen cevabı kendi kayıt düzenimize oturtmak. Aynı çatının altında iki durumun yan yana durması, ayrımın bir tercih değil bir olgu olduğunu gösteriyor.

Karşı tarafın sahibi, kapıda neyi değiştirebileceğinizi belirliyor. Aşağıdaki satırlar bu yazıdaki işlerin kapı tarafını yan yana koyuyor.

Karşı taraf sizin olduğunda bile kapı bedavaya gelmiyor. İki yan ayrı yerlerde ayrı çalıştığı için bir ad değişikliği iki tarafta birlikte planlanıyor; biri güncellenip öteki eski adla sormaya devam ederse çağrı karşılıksız kalıyor. Sahiplik işi kolaylaştırıyor, ortadan kaldırmıyor: kapının iki yanına da aynı anda dokunmak gerekiyor.

Alan adları kapıdan sonra tek taraflı değişmiyor

İşletme sahibi çoğu zaman “sonra değiştiririz” diye düşünüyor. Bir alanın adı kapıdan geçtikten sonra bu cümle geçerliliğini kaybediyor. Ad artık iki programın ortak borcu; tek başınıza değiştiremiyorsunuz.

Optik okuma tarafında bunun işleyen hâli görünüyor. Kuruma yeni bir form düzeni geldiğinde, uyarlamayı okuma servisinin tarafında yapıyoruz. Kapının öteki yanındaki kayıt düzenine dokunulmuyor; sınav kaydı yerinde duruyor ve sonuç yine aynı adlarla oraya iniyor. Kapının değeri tam burada görünüyor: bir taraf değişiyor, öteki taraf yerinde kalıyor.

Soru kırpma tarafı aynı mekanizmanın aynası. Orada adları ve cevabın biçimini karşı taraf koyuyor, biz koymuyoruz. Karşı taraf bir ad değiştirdiğinde uyarlama bize düşüyor ve takvimi de biz belirlemiyoruz. Kapının hangi yanında durduğunuz, uyum işinin kime düştüğünü belirliyor.

Takvim farkı burada önemli. Kapının iki yanı da bizde olduğunda bir ad değişikliği aynı planın içinde yürüyor. Karşı taraf bizim olmadığında değişikliğin zamanını da içeriğini de o taraf belirliyor; bize kalan iş, haber geldiğinde uyarlamayı sığdırmak. Aynı işin iki farklı takvime bağlanması, kapı kararının fiyat tarafını da değiştiriyor.

Buradan okurun işine yarayan bir kural çıkıyor. Bir alanın adını değiştirmek tek uygulamanın içinde bir düzenleme işi; arkasında ayrı çalışan bir program varsa aynı değişiklik bir uyum işine dönüşüyor. Bu yüzden ad listesini bir iç düzenleme gibi değil, verilmiş bir söz gibi ele alıyoruz. Hangi alanların kapıdan geçeceğini baştan daraltmak, sonradan uyum işine dönüşecek değişikliklerin sayısını da daraltıyor.

Sınırı da yazmak gerekiyor. Ad listesinin sabit kalması, kapının arkasındaki işin donduğu anlamına gelmiyor. Okuma servisinin içi istediği kadar değişebiliyor; değişmeyen şey, dışarıya verdiği sözün kendisi. Bu ayrım olmasaydı her iyileştirme bir uyum pazarlığına dönüşürdü.

Kapı kurulmayan iş: iki yarı aynı uygulamada olduğunda

Kapı kurmamak da bir karar. Kartvizite basılan kodun adresi sabitken tanıtım sayfasını panelden güncelleyen ürünümüzü şu an inşa ediyoruz; orada yönetim paneliyle ziyaretçinin açtığı tanıtım sayfası tek uygulamanın içinde duruyor. Aralarına API katmanı girmiyor. Bu kararın gerekçesini kâğıt menünün ve kataloğun yazılıma taşınması üzerine yazdığımız sayfada açtık; burada yalnız olgu olarak duruyor.

Mekanizma, yazının tezini tersten ispatlıyor. Kapıyı doğuran şey teknoloji seçimi değil, kayda dokunan ayrı bir program. Böyle bir program yoksa anlaşılacak bir ad listesi de yok. Panel bir kaydı güncelliyor, ziyaretçi sayfası aynı uygulamanın içinden okuyor; arada iki tarafın birbirine söz vermesi gereken bir nokta oluşmuyor. Kapı kurulmaması bir eksiklik değil, kapsam kararı.

Bu kararın kalıcı olduğunu da iddia etmiyoruz. Bir ürüne sonradan ayrı çalışan bir program eklenirse soru yeniden doğuyor. O an sorulacak şey yine aynı: kapı hangi kayda açılacak ve o kaydın hangi alanları geçecek. Soru bir kez sorulup kapanmıyor, her yeni programda yeniden soruluyor.

Bu yazının kapsamadığı bir alan daha kaldı. Dışarıdaki bir sisteme teslim noktası kurmak, karşı taraf cevap vermediğinde ne olacağı ve aynı belgenin ikinci kez gitmemesi başka bir konu; resmî belgenin karşı tarafa nasıl geçtiğini e-fatura bağlantısının işleyişi üzerine yazdığımız sayfada anlattık.

Geriye koddan önce konuşulacak tek soru kalıyor. Bu kayda sizin uygulamanızın dışından hangi program dokunacak? Cevabı siz biliyorsunuz ve sistem mimarisi çalışmasının ilk oturumunda bu soruyu masaya koyuyoruz.