Kısa cevap
API, yazılımların belirlenmiş kurallar ve veri biçimleri üzerinden birbiriyle iletişim kurmasını sağlayan arayüzdür.
Nerede işine yarar?
Hangi işlemin çağrılacağı, hangi parametrelerin kabul edildiği ve hangi yanıtların döneceği tanımlanır. Okuma ile veri değiştiren işlemler ayrı değerlendirilir. Kimlik doğrulama, hata yanıtları ve sürümleme, API kullanımının güvenilir olmasına yardımcı olur.
Tanımdan uygulamaya, kendi denemene.
Bir cümlede uygulaması
Bir sözlük teriminin tanımını sayfayı ayrıştırmak yerine tanımlı JSON uç noktasından okumak.
Neyle karıştırılmamalı?
API bir ürünün bütün iç verilerini otomatik olarak herkese açması demek değildir.
Düğmenin arkasında iki sistem konuşuyor.
Bir randevu ekranında uygun saatleri seçtiğini düşün. Tarayıcı takvimi gösterir, fakat hangi saatin boş olduğunu başka bir hizmet bilir. Aradaki API, takvimin hangi soruyu nasıl soracağını ve yanıtı nasıl okuyacağını tanımlar. Kullanıcıya görünen birkaç kutunun arkasında tarih aralığı, saat dilimi, hizmet türü ve kullanılabilirlik gibi açık kurallar bulunur. Bu kurallar belirsizse arayüz güzel görünürken yanlış saati gösterebilir.
Önce sözleşmeyi konuşuruz. Uygun saat listesinin boş olması hizmetin kapalı olduğu anlamına mı gelir, yoksa seçilen aralıkta yer bulunmadığını mı söyler? İstek zaman aşımına uğrarsa mevcut liste gösterilmeye devam edecek mi? Rezervasyon düğmesine iki kez basıldığında iki kayıt mı oluşacak? Bunlar yalnız geliştiricinin arka tarafta çözeceği ayrıntılar değildir. Ekrandaki boş durum, hata mesajı ve tekrar deneme davranışı bu yanıtlarla şekillenir.
Veriyi okumak ile değiştirmek aynı riski taşımaz. Saatleri listelemek mevcut kayda bakar; randevu oluşturmak yeni bir iş doğurur. Kullanıcının kimliği, yetkisi ve işlemin hangi kayda uygulanacağı sunucuda değerlendirilir. Arayüzde bir düğmeyi saklamak yetki kontrolünün yerine geçmez. Aynı isteği farklı bir istemci de gönderebilir. API tasarımı, doğru kişinin doğru işi yapabilmesini arayüzden bağımsız olarak tanımlamalıdır.
Entegrasyonun sürdürülebilirliği ilk başarılı yanıtla bitmez. Alan adları değişebilir, kullanım sınırı dolabilir, sağlayıcı bakım yapabilir. Hangi hatanın yeniden denenebileceği, hangi sonucun kullanıcıya gösterileceği ve hangi olayın kayıt altına alınacağı konuşulur. Kayıtlar sorunu anlamaya yetecek bilgiyi içermeli; özel verileri gereksizce çoğaltmamalıdır. Böylece iki sistem arasındaki ilişki yalnız mutlu akışta çalışan bir bağlantı olmaktan çıkar.
Bağlantı kuruldu. Peki anlaşma var mı?
Bir URL’ye istek göndermek
Örnek yanıt geldiği için entegrasyon tamam kabul edilir. Alanlar tahmin edilir, boş liste hata gibi gösterilir, zaman aşımında kullanıcı yeniden basar. İkinci işlem ilkini tekrarlar ve iki kayıt oluşabilir. Teknik bağlantı vardır ama davranış sözleşmesi zayıftır. Bir ekran görüntüsünde görünmeyen sorun, gerçek kullanımda destek yüküne dönüşür.
Davranışı tanımlanmış API
Başarılı ve başarısız örnekler belgelenir. Tekrar denemenin hangi koşulda güvenli olduğu, işlemin nasıl takip edileceği ve kullanıcının ne göreceği belirlenir. Arayüz yanıtın durumuna göre davranır. İki ekip birbirinin iç kodunu bilmeden ortak sözleşme üzerinden çalışabilir; değişiklikler de bu sözleşmeye etkisiyle değerlendirilir.
Bir API isteğinde neler olur?
Bir web API'sinde istemci belirli bir adrese istek gönderir; sunucu isteği değerlendirip bir yanıt döndürür. Adres, yöntem, başlıklar ve gerekiyorsa gövde birlikte isteği tarif eder. Yanıtın durum kodu ve verisi birlikte okunmalıdır. Başarılı görünen bir HTTP yanıtı, uygulamanın beklediği bütün alanların mevcut olduğu anlamına gelmez.
- Gerekli giriş alanlarını ve dönen veri biçimini belgeleyin.
- Eksik veri, yetkisiz istek ve servis kesintisi durumlarını tasarlayın.
- Gizli sunucu anahtarlarını tarayıcı koduna koymayın.
Örnek: bir sözlük maddesini istemek
Bir uygulamanın API terimini göstermek istediğini düşün. İstemci, sözlük servisinden bu kaydı ister. Servis terimin adını, açıklamasını ve ilgili bağlantılarını döndürür; uygulama bu veriyi kendi arayüzüne yerleştirir. Aynı bilgi web sayfasında, mobil uygulamada ve bir asistanda farklı görünümlerle kullanılabilir.
Terim bulunamadığında uygulama boş bir başarı ekranı göstermemelidir. Anlaşılır bir bulunamadı durumu sunmalı; bağlantı sorunu varsa yeniden deneme yolunu açıklamalıdır. Bu durumlar API tasarımının ve onu kullanan arayüzün ortak sorumluluğudur.
Başarı ve hata durumları
HTTP tabanlı bir API'de durum kodu yanıtın genel sınıfını belirtir. Örneğin 200 başarılı bir yanıtı, 404 istenen kaynağın bulunamadığını, 429 ise çok fazla istek gönderildiğini anlatabilir. Uygulama kodu, servis sözleşmesindeki hata gövdesini de okuyarak uygun davranışı seçer.
Hatalı isteği durmadan yeniden göndermek yerine hangi koşulda tekrar deneneceği tanımlanır. Okuma isteğinin tekrarı ile ödeme veya kayıt oluşturan isteğin tekrarı aynı riskte değildir. Aynı işlemin iki kez uygulanmasını önlemek, ilgili servisin açıkça tasarlaması gereken bir davranıştır.
Kimlik ile yetkiyi ayırmak
Kimlik doğrulama kimin istek yaptığını; yetkilendirme ise bu kişinin hangi işlemi yapabileceğini belirler. Giriş yapmış olmak bütün kayıtlara erişim hakkı vermemelidir. Gizli anahtarlar istemciye gönderilmez; sunucu her istekte gerekli izinleri kendi tarafında kontrol eder.
API kullanırken veri sınırı da önemlidir. Arayüzün ihtiyacı olmayan kişisel alanları göndermemek, günlüklerde gizli bilgileri saklamamak ve erişimi gerektiği kadar dar tutmak uygulama tasarımının parçasıdır.
API ile REST aynı şey mi?
API daha geniş bir kavramdır; bir tarayıcı, kütüphane veya işletim sistemi de API sunabilir. REST ise ağ üzerinden çalışan sistemler için bir mimari yaklaşımdır. Her API web API'si olmadığı gibi her web API'si de REST kurallarını izlemek zorunda değildir.
İşin içinde sorulacaklar.
API her zaman internet üzerinden mi çalışır?
Hayır. API bir yazılımın sunduğu programatik arayüzdür. Tarayıcının seslendirme veya konum gibi yetenekleri de API üzerinden kullanılabilir; bir kütüphanenin fonksiyonları da bir arayüz oluşturur. Web projelerinde terim sıkça HTTP ile erişilen hizmetler için kullanıldığı için yalnız dış sunucu çağrısı sanılır. Hangi API’den söz edildiğini belirtmek, bağımlılıkları ve izinleri doğru anlamayı sağlar.
API anahtarını frontend’e koyabilir miyiz?
Özel bir sunucu anahtarı tarayıcıya gönderilirse ziyaretçi tarafından okunabilir. Bazı servisler herkese açık istemci anahtarları tasarlar; bunların yetkileri ayrıca sınırlanır. Anahtarın adı değil, hangi işlemlere izin verdiği belirleyicidir. Gizli yetki gerektiren çağrılar uygun sunucu katmanından yapılır. Yalnız alan adını kısıtlamak veya kodu küçültmek, bir sırrı tarayıcıda gizli tutmaz.
Bir API değişince bütün uygulama bozulur mu?
Değişikliğin sözleşmeye etkisine bağlıdır. Yeni isteğe bağlı alan çoğu istemciyi etkilemezken kullanılan bir alanın kaldırılması akışı bozabilir. Bu nedenle bağımlılıklar, sürüm politikası ve geçiş süresi görünür olmalıdır. Yanıtı tek bir uyarlama katmanında işlemek değişikliği yönetmeyi kolaylaştırabilir. Yine de gerçek akışın hata davranışı ve veri anlamı kontrol edilmeden yalnız alan adlarını eşlemek yeterli değildir.
Tek randevunun sözleşmesini yaz.
Bir rezervasyon özelliği için kod yazmadan kısa bir API taslağı hazırla. Hedef, farklı ekiplerin aynı işlemden aynı sonucu beklemesini sağlamak. Örnekte gerçek müşteri verisi veya çalışan gizli anahtar kullanma; alan adları ve temsili değerler yeterlidir.
İyi API tasarımı, iki sistemin konuşmasını sağlarken aradaki belirsizliği azaltır. Kullanıcının gördüğü hata, bekleme ve başarı durumları bu anlaşmanın ekrandaki karşılığıdır.
Bağlantılı kavramlar
- JSONJSON, nesne, dizi, metin, sayı ve temel değerlerle yapılandırılmış veri taşımaya yarayan metin biçimidir.
- MCPMCP, modellerin araç ve kaynaklarla tanımlı bir protokol üzerinden çalışabilmesine yönelik bağlantı yaklaşımıdır.
- SSRSSR, bir sayfanın HTML içeriğinin istek sırasında sunucuda oluşturulması yaklaşımıdır.