Telefonunuzdaki bir uygulama hava durumunu gösterirken veriyi başka bir hizmetten alabilir. Bu iletişim, önceden belirlenmiş kurallara göre gerçekleşir. API, yani uygulama programlama arayüzü, yazılımların hangi işlemleri hangi biçimde yapabileceğini tanımlar. Tek bir teknoloji adı değil, daha geniş bir arayüz kavramıdır.
İsteği ve yanıtı ayrı düşünün
Bir hava durumu uygulaması belirli konum için veri ister. Hizmet de koşullar uygunsa sıcaklık ve tahmin bilgileri döndürür. İstekte hangi alanların gerektiği, yanıtın nasıl düzenlendiği ve hata durumlarının nasıl bildirildiği arayüzün parçasıdır.
Bir restoran benzetmesi yapılabilir: menü, hangi isteklere yanıt verilebileceğini gösterir. Ancak mutfaktaki bütün işlem ayrıntılarını müşteriye açmaz. Benzer biçimde API, bir hizmetin iç yapısını bilmeden belirli yetenekleri kullanmayı sağlar. Bu benzetme kavramı anlatır; gerçek sistemin güvenliğini veya performansını açıklamaz.
Web API ile tarayıcı API'sini ayırın
Web üzerinden çağrılan bir veri hizmetiyle tarayıcının sunduğu konum veya depolama arayüzleri aynı şey değildir. Her ikisi de API örneği olabilir. Birinin çalışması uzaktaki hizmete, diğerinin çalışması tarayıcı yeteneklerine ve izinlerine bağlı olabilir.
Bu ayrım özellikle ürün açıklamalarında önemlidir. “API desteği var” cümlesi tek başına yeterli bilgi vermez. Hangi işlemler destekleniyor, hangi platformlarda kullanılabiliyor ve hangi koşullarda erişiliyor? İlgili dokümana bakmadan bütün ihtiyaçların karşılanacağını varsaymayın.
Veri sözleşmesini somutlaştırın
Bir hava durumu yanıtında sıcaklık alanı bulunsa bile birimi ve ölçüm zamanı bilinmelidir. Aynı sayı farklı birimlerde farklı anlam taşır. Eksik veri, boş alan ve güncel olmayan değerler uygulama tarafından açıkça ele alınmalıdır.
Entegrasyon öncesi kontrol soruları:
- Hangi işlem veya veriye ihtiyaç var?
- İstekte zorunlu alanlar neler?
- Yanıt hangi biçimde geliyor?
- Birim ve tarih bilgileri nasıl veriliyor?
- Veri bulunamadığında ne oluyor?
- Hizmetin kullanım sınırı ve koşulları neler?
Bu sorular, kod yazmadan önce beklenen davranışı anlaşılır kılar.
Erişim anahtarını kullanıcı verisinden ayırın
Bazı hizmetler isteklerin hangi uygulamadan geldiğini anlamak için anahtar veya başka kimlik doğrulama yöntemleri kullanır. Bu bilgiler herkese açık dosyalara rastgele eklenmemelidir. Hangi anahtarın istemcide kullanılabileceği, hangisinin sunucuda saklanması gerektiği ilgili hizmete göre değerlendirilir.
Bir anahtara sahip olmak da bütün verilere sınırsız yetki anlamına gelmez. İzinler, kota ve hesap koşulları bulunabilir. Test ortamındaki erişimle canlı sistemin erişimini karıştırmayın. Günlüklerde hata araştırırken sırların ve kişisel verilerin gereksiz yere yazılmasını önleyin.
Hata durumunu ürün deneyimine dâhil edin
Ağ kesilebilir, hizmet yavaşlayabilir veya istenen veri bulunamayabilir. Uygulamanın yalnızca başarılı yanıtı tasarlanırsa kullanıcı boş ekranla karşılaşabilir. Eski veriyi gösteriyorsanız tarihini belirtmek, belirsiz bir değer sunmaktan daha anlaşılırdır.
Küçük bir entegrasyonda önce temsilî örneklerle çalışın; başarılı sonuç kadar eksik veri ve erişim hatasını da deneyin. API'nin değeri yalnızca iki yazılımı bağlamak değildir. Açık bir sözleşme sayesinde uygulamaların sınırlarını ve sorumluluklarını anlaşılır biçimde paylaşmalarını sağlar.
Bir deneme uygulamasında sıcaklık verisini alıp ekrana yazdığınızı düşünün. Yanıtta değer bulunmadığında sıfır göstermek, gerçekten sıfır derece ölçülmüş izlenimi yaratabilir. Bunun yerine veri yok durumunu açıkça tasarlayın. Aynı şekilde ölçüm saati eskiyse değerin ne zaman alındığı belirtilmelidir. Bu örnek, API entegrasyonunun yalnızca veri çekmekten ibaret olmadığını gösterir. Gelen bilginin anlamını doğru aktarmak da uygulamanın görevidir. Test örneklerinize boş yanıt, geçersiz istek ve gecikmiş veri ekleyin. Başarısız durumlarda kullanıcının ne göreceğini önceden belirlemek, sorun çıktığında rastgele mesaj üretmekten daha tutarlı bir deneyim sağlar.
