REST ve SOAP API Nedir?
API (Uygulama Programlama Arayüzü) başlıklı yazımda da belirttiğim üzere API’ler aracılığıyla bir uygulamanın, servisin ve/veya platformun sahip olduğu yeteneklere farklı bir uygulamadan REST, SOAP, XML-RPC ve diğer web teknolojilerini kullanarak erişebiliyor ve hatta işlemler gerçekleştirebiliyoruz.
Uygulamamamız içerisinden Twitter API1'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 API2 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 TransferTemsili Durum Transferi). REST API öncesinde SOAP ile ilgili kısa birkaç bilgi vermekte fayda var.
SOAP (Simple Object Access Protocol)
SOAP web servis çağrılarında RPC (Remote Procedure Call) modelini kullanan, istemci/sunucu mantığına dayalı bir protokol olarak ifade edilebilir. Metotları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 Soap3, SOAP4 ve SOAP vs REST 101: Understand The Differences5 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)
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 duymaz6.
- 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/listelemerPOST
Yeni veri ekler/oluştururPUT
Var olan bir veriyi günceller/üzerine yeni veri eklerDELETE
Veri silerPATCH
Verinin bölümünü güncellerOPTIONS
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?
- 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.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;
- 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:
- How SOAP and REST work with XML/JSON response? @stackoverflow
- SOAP vs REST (differences) @stackoverflow
- Understanding SOAP and REST Basics And Differences @smartbear
- REST Vs SOAP, The Difference Between Soap And Rest @spf13
- Why SOAP sucks @somebits
- SOAP vs. REST: A Look at Two Different API Styles @upwork