API ile web servisi aynı kapsamda değildir. API, bir uygulamanın başka bir uygulamanın işlev veya verilerine erişmesini sağlayan arayüzdür; web servisleri ise uygulamalar arasındaki iletişimi ağ üzerinden kurar.
Ağ Üzerindeki İstek ve Yanıt
İstek URL’si hedef kaynağı belirtir, yöntem istenen işlem türünü bildirir, başlıklar da içerik türü gibi ek bilgileri taşır. Örneğin bir isteğin adresi kaynak konumunu, başlıkları ise isteğin nasıl yorumlanacağına yarayan bilgileri gösterir.
GET ve POST İsteğinin Taşıdığı Anlam
GET, bir kaynağın temsilini istemek için kullanılır; HTTP standardına göre GET isteği gövde içermemelidir. POST ise hedef kaynağın işleyişine göre veri gönderebilir veya işlem başlatabilir.
| Özellik | GET | POST |
|---|---|---|
| Amaç | Kaynak verisini ister | Veri gönderebilir veya işlem başlatabilir |
| İstek gövdesi | Standarda göre içermez | Hedef kaynağın işleyişine bağlıdır |
| İstek yönü | Kaynağı isteme | Hedefe veri veya işlem iletme |
GET yanıtının kodu isteğin sonucunu bildirir; yöntem adı tek başına yanıtın başarılı olup olmadığını söylemez.
Yanıttaki Kod ve Veri Biçimi
401 kimlik doğrulama bilgisinin eksik ya da kabul edilmemiş olduğunu, 403 ise isteğin reddedildiğini belirtir. Yanıt gövdesindeki JSON, yapılandırılmış veriyi metin biçiminde taşır ve JavaScript dışındaki programlama dilleri de bu veriyi okuyup üretebilir.
İstemci, istediği yanıt biçimini Accept başlığıyla bildirir; gönderdiği içeriğin biçimini Content-Type başlığı belirtir. API yanıtı JSON veya XML gibi biçimlerde olabilir.
Web API Tasarımında REST ve SOAP
REST, kaynakları URI’lerle tanımlayan ve bu kaynaklarla HTTP yöntemleri üzerinden çalışmayı düzenleyen bir mimari yaklaşımdır. REST’te durumsuzluk, her isteğin sunucunun isteği anlayıp işlemesi için gereken bilgileri taşıması demektir; sunucu önceki isteklerden kalan istemci bağlamına dayanmaz.
REST yanıtları önbelleğe uygun olarak tanımlanabilir ve bu yanıtların yeniden kullanılması performansı artırıp sunucu yükünü azaltabilir. SOAP ise HTTP üzerinden de taşınabilen bir mesajlaşma protokolüdür. SOAP mesajı HTTP ile iletildiğinde, HTTP’nin kendi anlamları geçerliliğini korur.
İstemci İçin Belgeler ve Tarayıcıdaki Sınır
OpenAPI, bir HTTP API’nin yeteneklerini kaynak koda erişmeden insanların ve makinelerin anlayabileceği biçimde tarif eden, programlama dilinden bağımsız bir arayüz belirtimidir. Tarayıcıdaki JavaScript, Fetch API ile HTTP isteği gönderip yanıtı işleyebilir; yanıt gövdesini JSON olarak okuyabilir.
CORS, sunucunun hangi kaynaklardan gelen web sayfalarının yanıtı okuyabileceğini HTTP başlıklarıyla bildirmesini sağlar. Bazı tarayıcı isteklerinden önce OPTIONS ön isteği gönderilebilir; tarayıcı bu istekle sunucunun kullanılacak yönteme ve başlıklara izin verip vermediğini sorar.
Belirtiye Göre İlk Okuma
Yanıt kodunun ilk rakamı sınıfı belirtir: 2xx başarı, 4xx istemci hatası, 5xx sunucu hatasıdır; 1xx bilgi, 3xx yönlendirme sınıfıdır. İstek kimlik doğrulama bilgisi taşımıyorsa 401, kimliği tanınmasına rağmen erişim yetkisi yetersizse 403 anlamlıdır.
Seçim Ölçütü: Hangi Bilgiye İhtiyaç Var?
Sunucunun iç yapısına erişmeden arayüzün nasıl kullanılacağını anlamak için adres, veri biçimi, yanıt kodları ve erişim yöntemini arıyorsan API sözleşmesi düzeyindeki bilgi yeterlidir. Belirli bir HTTP yanıtını çözümlemen gerekiyorsa, yanıt kodundan başlayıp ihtiyacın olan açıklama düzeyini seç.