XML API nedir?

XML API, uygulamaların birbirleriyle XML biçimindeki istek ve yanıtlar üzerinden veri alışverişi yapmasını sağlayan programlama arayüzüdür. İstek veya yanıt XML içerebilir; örneğin gövdesiz GET isteğine XML yanıtı da mümkündür. Bütün işlemler çift yönlü XML gövdesi taşımak zorunda değildir. Bu yapı SOAP gibi katı kurallı servislerde veya HTTP üzerinden çalışan özel XML servislerinde kullanılabilir. XML API bir programlama dili değil, uygulamalar arasındaki veri iletişimi yöntemidir.

XML API nasıl çalışır?​

İstemci uygulama önce servisin beklediği adresi, HTTP yöntemini, kimlik doğrulama biçimini ve XML şemasını öğrenir. Daha sonra istenen işlemi belirten bir XML gövdesi gönderir. Sunucu XML'i ayrıştırır, alanları doğrular ve sonucu XML olarak döndürür.

Varsayımsal stok servisi için aşağıdaki bölüm istek gövdesi ve ilgili başlıkları gösterir; tam ham HTTP mesajı değildir, Host ve gövde uzunluğu gibi taşıma ayrıntılarını HTTP istemcisi tamamlar:


Başarılı yanıt varsayımsal olarak şöyle olabilir:


Burada UrunKodu istek parametresidir. MevcutAdet ve Durum ise sunucunun ürettiği sonuç alanlarıdır. Gerçek bir serviste etiket adları, zorunlu alanlar ve yanıt yapısı mutlaka o servisin teknik sözleşmesine göre değiştirilmelidir.

XML API'lerde en sık karşılaşılan yapıların farkı şöyledir:


İstemci tarafında XML API kullanırken genel uygulama sırası şöyledir:

1. Servisin dokümantasyonundan uç noktayı, HTTP yöntemini, gerekli başlıkları, kimlik doğrulamayı ve XML şemasını belirleyin.
2. Önce en küçük geçerli XML isteğini hazırlayın. Kök eleman ve zorunlu alt elemanlar doğru olmalıdır; XML bildirimi her belgede zorunlu değildir, kullanılıyorsa kodlamayla tutarlı olmalıdır.
3. Servisin istediği içerik türünü kullanın: genel XML örneğinde application/xml, SOAP 1.2’de genellikle application/soap+xml, SOAP 1.1 HTTP bağlamasında text/xml kullanılır. Tek başlığı bütün servislere taşımayın. Sunucu yanıtının XML olacağını belirtmek için gerekliyse Accept: application/xml başlığını ekleyin.
4. Önce HTTP durumunu, ardından XML yanıtındaki uygulama durumunu kontrol edin. HTTP isteği başarılı olsa bile XML içinde işlem hatası bulunabilir.
5. Yanıtı XML ayrıştırıcısıyla okuyun; metin aramasıyla etiketleri ayıklamak yerine kök elemanları, ad alanlarını ve veri türlerini dikkate alın.
6. Başarılı sonucu uygulamanızdaki veri modeline aktarın. Hata yanıtını, ham XML'i kullanıcıya göstermek yerine anlaşılır bir uygulama mesajına dönüştürün.

Örneğin HTTP isteği teknik olarak ulaşıyor fakat MevcutAdet okunamıyorsa sorun yalnızca ağ bağlantısı değildir. Etiket adı farklı olabilir, XML ad alanı kullanılabilir veya sunucu hata yapısını döndürüyor olabilir. Hassas alanları maskeleyerek sınırlı tanı çıktısını servisin şemasıyla karşılaştırın; parola ve kişisel veriler içeren ham yanıtı bütünüyle günlüğe yazmayın. Güvenilmeyen XML için ayrıştırıcının DTD/dış varlık çözümlemesini kapalı tutan güvenli ayarlarını kullanın; varsayılanı dil ve sürüme göre kontrol edin.

Sık yapılan hatalar​

XML'in büyük-küçük harf duyarlı olduğu unutulmamalıdır; UrunKodu ile urunkodu aynı alan değildir. Kapanmayan etiketler, yanlış iç içe geçirme, hatalı özel karakter kullanımı ve eksik XML kaçışları da ayrıştırma hatasına yol açar. Metin içinde & karakteri gerektiğinde XML kurallarına uygun biçimde yazılmalıdır.

Bir diğer hata, HTTP durum kodunu tek başına başarı kabul etmektir. Servis HTTP düzeyinde yanıt verse bile XML gövdesinde doğrulama veya iş kuralı hatası bulunabilir. Ayrıca SOAP servisine SOAP zarfı olmadan sıradan XML göndermek ya da XML bekleyen servise JSON göndermek beklenen sonucu vermez. Kimlik bilgilerini XML gövdesine rastgele eklemek yerine servisin istediği kimlik doğrulama yöntemini uygulayın.

Sık sorulan sorular​

Etiket adı doğru olduğu hâlde alan neden bulunamıyor?​

Yanıt bir XML namespace kullanıyor olabilir. Yalnız yerel etiket adına bakmak yeterli olmayabilir; ayrıştırıcıda beklenen ad alanını eşleştirin. Prefix yazımı değişse de belirleyici olan ad alanı URI’si ve yerel addır.

Zaman aşımı alan XML isteğini tekrar göndermek güvenli mi?​

Sonuç alınamaması sunucunun işlemi yapmadığını kanıtlamaz. Stok sorgusuyla ödeme veya sipariş oluşturma aynı değildir. Servisin idempotency anahtarı ya da işlem sorgulama yöntemini kullanın; durum değiştiren isteği körlemesine tekrarlamayın.