API (Application Programming Interface/Uygulama Programlama Arayüzü) Nedir? Ne İşe Yarar? başlıklı yazımda da belirttiğim üzere API’ler aracılığıyla bir uygulamanın, servisin ve/ya platformun sahip olduğu yeteneklere farklı bir uygulamadan REST, SOAP, JavaScript, XML-RPC ve diğer web teknolojilerini kullanarak erişebiliyor ve hatta işlemler gerçekleştirebiliyoruz. Örneğin, uygulamamamız içerisinden Twitter API‘yi çağırarak API kapsamında bize sunulan Twitter özelliklerini (tweet atma, görüntüleme, hesap takip etme vb.) kullanabiliriz. Peki bu özellikleri neden Twitter’ın kendisi üzerinden gerçekleştirmiyoruz? Şöyle düşünebiliriz. Aynı anda bir de Open Weather Map API erişimimiz olsun. Bu durumda her iki servisi birleştirerek kritik hava değişimlerini tweet olarak erişim sağladığımız hesaplar üzerinde paylaşabiliriz. Gerisi ihtiyaçlarınıza ve hayal gücünüze kalıyor. Günümüzde, web services olarak ifade edilen iki tip yaygın olarak kullanılmakta; SOAP (Simple Object Access Protocol/Basit Nesne Erişim Protokolü) ve REST (Representational State Transfer/Temsili Durum Transferi). REST API öncesinde SOAP ile ilgili kısa bir kaç bilgi vermekte fayda var.

SOAP (Simple Object Access Protocol/Basit Nesne Erişim Protokolü) Nedir?

SOAP web servis çağrılarında RPC (Remote Procedure Call/Uzak Yordam Çağırısı) modelini kullanan, istemci/sunucu mantığına dayalı bir protokol olarak ifade edilebilir. Metodların call edilmesi üzerine alınan response da dahil sürecin tamamı XML olarak ve genellikle HTTP (Hyper Text Transfer Protocol) protokolü (bazende TCP/IP) kullanılarak iletilir. XML yapısı sebebiyle REST’e kıyasla daha katı bir işleyişe sahip olduğu için pek tercih edilmemektedir. Detaylı bilgi için XML Soap, SOAP @Wikipedia ve SOAP vs REST 101: Understand The Differences @SOAP IU sayfalarını inceleyebilirsiniz. Örnek bir istemci (client) talebi (request) şu şekildedir:

POST http://www.stgregorioschurchdc.org/cgi/websvccal.cgi HTTP/1.1 
Accept-Encoding: gzip,deflate 
Content-Type: text/xml;charset=UTF-8 
SOAPAction: "http://www.stgregorioschurchdc.org/Calendar#easter_date" 
Content-Length: 479 
Host: www.stgregorioschurchdc.org 
Connection: Keep-Alive 
User-Agent: Apache-HttpClient/4.1.1 (java 1.5) 
<?xml version="1.0"?> 
<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:cal="http://www.stgregorioschurchdc.org/Calendar"> 
<soapenv:Header/> 
<soapenv:Body> 
   <cal:easter_date soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> 
   <year xsi:type="xsd:short">2014</year> 
</cal:easter_date> 
</soapenv:Body> 
</soapenv:Envelope>

Yukarıdaki örnek istemci talebine karşılık sunucu (server) yanıtı (response) ise şu şekilde olacaktır.

HTTP/1.1 200 OK 
Date: Fri, 22 Nov 2013 21:09:44 GMT
Server: Apache/2.0.52 (Red Hat)
SOAPServer: SOAP::Lite/Perl/0.52
Content-Length: 566
Connection: close
Content-Type: text/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
   <namesp1:easter_dateResponse 
xmlns:namesp1="http://www.stgregorioschurchdc.org/Calendar">    
<s-gensym3 xsi:type="xsd:string">2014/04/20</s-gensym3>
</namesp1:easter_dateResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

XML satırlarının öncesinde yer alan 200 OK ve benzeri header bilgilerine yazının alt bölümlerinde ayrıca değineceğim.

Şimdi de REST API’ye bir bakalım.

REST (REpresentational State Transfer/Temsili Durum Transferi) Nedir?

REST API, SOAP ve WSDL tabanlı web servislerinin daha basite indirgenmiş hali olarak nitelendirilebilir. Bu amaçla internet tarayıcısı sayfa işlemlerinin bir parçası olan HTTP protokolünü (GET, POST, PUT DELETE gibi talep tipleri) kullanır. Böylelikle REST API geliştiricilere yaygın, pratik ve oldukça esnek bir kullanım olanağı sunduğu gibi, minimum içerikle veri alıp gönderdiği için de daha hızlıdır.

REST API, istemci ve sunucu arasında XML, JSON, HTML, TEXT başta olmak üzere pek çok formatta veri taşıyarak uygulamaların haberleşmesini sağlar. REST standartlarına uygun yazılan web servislerine RESTful servisler denir.

SOAP ve REST karşılaştırması yapmak ve her iki web servisininin artı ve eksilerini değerlendirmek gerekirse;

  • REST API, istemci-sunucu iletişimiyle ilgili bir mimaridir.
  • REST API, SOAP, RPC gibi kompleks mimariler yerine HTTP protokolü üzerinden işler.
  • REST API, SOAP, RPC’nin aksine basit ve hızlıdır.
  • REST API’nin SOAP gibi katı standartları yoktur.
  • Elbette SOAP üzerinde güvenlik sağlamak katı kurallar sebebiyle daha kolay ve hızlı bir şekilde sağlanabilirken süreç REST için karmaşık bir hale gelebilmekte.
  • REST API SOAP gibi proxy kullanmaya ve WSDL’e gereksinim duymaz.
  • SOAP, güvenlik protokollerini bünyesinde barındırır ve state bilgisini talep ve yanıtlarda saklar.

HTTP Methodları (Verb)

GET: Veri görüntüler/listelemer
POST: Yeni veri ekler/oluşturur
PUT: Var olan bir veriyi günceller/üzerine yeni veri ekler
DELETE: Veri siler
PATCH: Verinin bölümünü günceller
OPTIONS: Kabul edilen istekler konusunda bilgi iletir

REST API Gereksinimleri

Sunucu bu tiplerden hepsini ya da bir kaçına cevap verebilir. Peki, bu işlemlerin gerçekleştirilebilmesi için REST API’nin ne gibi gereksinimleri karşılaması gerekir?

  • Doğrulama (Validation)
  • Kullanıcı Doğrulama (Authentication)
  • Ön Bellek (Caching)
  • Sayfalama
  • Sıralama/Filtreleme
  • Versiyonlama
  • Yetkilendirme/Yetki Kısıtlama (Authorization)

Örnek bir REST talebi şöyledir:

GET http://www.catechizeme.com/catechisms/catechism_for_young_children/daily_question.js HTTP/1.1
Accept-Encoding: gzip,deflate
Host: www.catechizeme.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Bu örnek talebe ise verilen yanıt şu şekilde olacaktır:

HTTP/1.1 200 OK
Date: Fri, 22 Nov 2013 22:32:22 GMT
Server: Apache
X-Powered-By: Phusion Passenger (mod_rails/mod_rack) 3.0.17
ETag: "b8a7ef8b4b282a70d1b64ea5e79072df"
X-Runtime: 13
Cache-Control: private, max-age=0, must-revalidate
Content-Length: 209
Status: 200
Keep-Alive: timeout=2, max=100
Connection: Keep-Alive
Content-Type: js; charset=utf-8
{
   "link": "catechisms\/catechism_for_young_children\/questions\/36",
   "catechism": "Catechism for Young Children",
   "a": "Original sin.",
   "position": 36,
   "q": " What is that sinful nature which we inherit from Adam called?"
}

REST API Response Yaygın HTTP Status Kodları

Sıklıkla karşılaşılan status değerlerine dair kısa açıklamalar eklemek gerekirse;

200OKİlgili listeleme/görüntüleme işleminin başarılı olduğunu belirtir.
201CREATEDVeri eklenme işlemi sonunda verinin kendisi 201 ile döner.
204NO CONTENTSilinme işleminin ardından ilgili verinin olmadığını belirtir.
400BAD REQUESTTalepte (kayıt ekleme, güncelleme, silme vb.) gönderilen talebin doğrulanamadığı (validation) durumları ifade eder.
401UNAUTHORIZEDTalep yetkilendirilen kullancının yetkileri ötesindeyse (sınırlandırma) 403 status kodu dönecektir.
403FORBIDDENİşlemler kullancının oturum gerçekleştirmesini zorunlu kılıyorsa ve oturum gerçekleştirilmemişse 401 status bildirimi alınacaktır.
404NOT FOUNDKullanıcının istek yaptığı URL yok ya da geçersiz ise 404 status dönecektir.
405METHOD NOT ALLOWEDİstek izin verilen dışında bir tip barındırıyor ise bu status dönecektir. Örneğin, GET yerine POST kullanmak gibi.
429TOO MANY REQUESTSKullanıcı belirtilen sayıdan fazla ya da karmaşık bir istekte (saatlik, dakikalık vb.) bulunmuşsa bu status dönecektir.

Bu status bildirimlerini genel gruplandırmalar altında ifade etmek gerekirse;

1xx – Bilgilendirme
2xx – Başarılı İşlem
3xx – Yönlendirme
4xx – Kullanıcı Kaynaklı Hata
5xx – Server Kaynaklı Hata

Konuyla ilgili olarak karşılaştırmalar ve ek diğer detaylar için aşağıdaki yazıları inceleyebilirsiniz:

Leave a Reply