REST ve SOAP API Nedir?

Güncelleme Yayın

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 birkaç bilgi vermekte fayda var.

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

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.alanadi.com/cgi/websvccal.cgi HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://www.alanadi.com/Calendar#date"
Content-Length: 479
Host: www.alanadi.com
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.alanadi.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)

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;

  1. REST API, istemci-sunucu iletişimiyle ilgili bir mimaridir.
  2. REST API, SOAP, RPC gibi kompleks mimariler yerine HTTP protokolü üzerinden işler.
  3. REST API, SOAP, RPC’nin aksine basit ve hızlıdır.
  4. REST API’nin SOAP gibi katı standartları yoktur.
  5. 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.
  6. REST API SOAP gibi proxy kullanmaya ve WSDL’e gereksinim duymaz.
  7. SOAP, güvenlik protokollerini bünyesinde barındırır ve state bilgisini talep ve yanıtlarda saklar.

HTTP Methodları (Verb)

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

REST API Gereksinimleri

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

  1. Doğrulama (Validation)
  2. Kullanıcı Doğrulama (Authentication)
  3. Ön Bellek (Caching)
  4. Sayfalama
  5. Sıralama/Filtreleme
  6. Versiyonlama
  7. Yetkilendirme/Yetki Kısıtlama (Authorization)

Örnek bir REST talebi şöyledir:

GET http://www.alanadi/data.js HTTP/1.1
Accept-Encoding: gzip,deflate
Host: www.alanadi.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
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": "alanadi\/\/item\/36",
   "item": "Title",
   "a": "...",
   "position": 36,
   "q": "..."
}

REST API Response Yaygın HTTP Status Kodları

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

Durum Kodu Açıklama
200 - OK İlgili listeleme/görüntüleme işleminin başarılı olduğunu belirtir.
201 - CREATED Veri eklenme işlemi sonunda verinin kendisi 201 ile döner.
204 - NO CONTENT Silinme işleminin ardından ilgili verinin olmadığını belirtir.
400 - BAD REQUEST Talepte (kayıt ekleme, güncelleme, silme vb.) gönderilen talebin doğrulanamadığı (validation) durumları ifade eder.
401 - UNAUTHORIZED Talep yetkilendirilen kullancının yetkileri ötesindeyse (sınırlandırma) 403 status kodu dönecektir.
403 - FORBIDDEN İşlemler kullancının oturum gerçekleştirmesini zorunlu kılıyorsa ve oturum gerçekleştirilmemişse 401 status bildirimi alınacaktır.
404 - NOT FOUND Kullanıcının istek yaptığı URL yok ya da geçersiz ise 404 status dönecektir.
405 - METHOD 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.
429 - TOO MANY REQUESTS Kullanı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;

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

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

  1. How SOAP and REST work with XML/JSON response? @stackoverflow
  2. SOAP vs REST (differences) @stackoverflow
  3. Understanding SOAP and REST Basics And Differences @smartbear
  4. REST Vs SOAP, The Difference Between Soap And Rest @spf13
  5. Why SOAP sucks @somebits
  6. SOAP vs. REST: A Look at Two Different API Styles @upwork