Api Nedir ?
Kısaca api, herhangi bir uygulamanın belli işlevlerini diğer uygulamalarında kullanabilmesi için oluşturulmuş bi modüldür.
SOAP (Simple Object Access Protocol - Basit Nesne Erişim Protokolü) Nedir ?
SOAP (Basit Nesne Erişim Protokolü) dağıtık uygulamalarda ve web servislerinin haberleşmesinde kullanılmak üzere tasarlanan, RPC (Remote Procedure Call) modelini kullanan, istemci/sunucu mantığına dayalı bir protokoldür. Daha genel olarak SOAP, web üzerinden fonksiyonları kullanmak için geliştirilmiş bir sistemin XML tabanlı kurallar topluluğudur. SOAP ile ilgili bütün mesajlar XML formatında iletililir.
Zaten böyle bir protokol var neden rest kullanmalıyım diyebilirsiniz. Şimdi rest hakkında bir şeylerden bahsetmeye başlayalım.
REST (Representational state transfer) Nedir ? - REST client-server iletişimiyle ilgili bir mimari. - SOAP, RPC gibi kompleks mimarilerle sağlamak yerine, HTTP protokolü üzerinden saglamak.
- SOAP, RPC'nin aksine basit ve hafiftirler.
- Esnek olup, SOAP gibi keskin standartları yoktur.
- SOAP ile en büyük farkı, SOAP gibi bizi proxy kullanmaya, bir WSDL'e zorlamıyor olması.
- Entegre etmesi kolay.
REST İstek Tipleri Ve Anlamları
- GET: Veri listeleme - veri görüntülemek için kullanılır.
- POST: Veri eklemek için kullanılır. - PUT: Veriyi Güncelleme isteği olarak kullanılır. - PATCH: Verinin sadece bir parçasını güncellemek için kullanılır. Örneğin bir issue'nun durumunun aktiften çözüldü haline getirilmesi. - DELETE: Veriyi silmek için kullanılır. - OPTIONS: Bir api urline Options isteği yapıldığında o url in hangi istekleri kabul ettiği bilgisi verilir. Örneğin: ... Server: Apache/2.4.1 (Unix) OpenSSL/1.0.0g Allow: GET,HEAD,POST,OPTIONS,TRACE Content-Type: httpd/unix-directory ...
Yukarıdaki resme baktığımızda Bütün rest uçlarının bir tane Resource interface inin implemente ettiğini görüyoruz.
Örneğin Orders yani siparişler Resource una baktığımızda GET isteğinde sipariş listesini döndüğünü POST da yeni bir sipariş oluşturduğunu PUT isteğinin ise kullanılmadığını görüyoruz.
Şöyle bir neden kullanılmadığını düşünürsek. Yukarıdaki verdiğimiz tanımlarda PUT isteğini bir Resource daki bir veriyi güncellemek için kullandığımızı belirtmiştik. Bu tanıma göre /orders api ucunda update edilecek herhangi bir sipariş yok. Bu durumda tüm siparişleri güncellemeyeceğimize göre PUT ve DELETE metodları kullanılmıyor. (istisnayi durumlar dışında. Örneğin bulk yani toplu yapılan bazı durumlardaki işlemler.)
/orders/<id> bölümünde ise durum farklı. Bu durumda hangi sipariş üzerinde işlem yaptığımız belli. PUT isteğinde hangi siparişin güncelleneceği ya da DELETE isteği ile silineceğini görüyoruz.
REST Apinin Hangi Gereksinimlerimizi Karşılıyor Olması Lazım ?
- Versiyonlama: Yazdığınız Rest api sadece kendi içinizde değilde herhangi bir kullanıcı tarafından da kullanabilir. Örnek verecek olursak Twitter. Bu örneğe göre Api de yaptığımız herhangi bir değişiklik implementasyon da değişiklikler oluşturabilir. Burada apiyi imlemente eden siz olmadığınıza göre Apide değiştirdiğiniz şey apinizi kullanan kullanıcılar tarafından sıkıntıya sebep olacaktır. Bu gibi değişiklikler kritik değil ise toplu bir şekilde versiyon haline getirmek daha mantıklı olacaktır.
- Sayfalama: Apimizin sağladığı verinin tamamını tek seferde vermek sisteme yük getirebilir. Örnek verecek olursak bir kullanıcının siparişler sayfası olduğunu düşünelim ve bu kullanıcının 1000 tane siparişi var. Bu veriyi tek seferde limitsiz vermek sisteme bir hayli yük bindirecektir. Bu gibi sıkıntıları önlemek için belli aralıklar ile (örneğin 20 şerli) veriyi parçalı olarak vermek en mantıklısı olacaktır.
- Kullanıcı Dogrulama (Authentication): Her durumda Public bir veri veriyor olmayabiliriz. Bu gibi durumlarda kullanıcıdan api üzerinden login olup o şekilde veriyi almasını istememiz gerekiyor. Örneğin kullanıcılara api üzerinden mesajlaşma geçmişlerini veriyoruz. Kullanıcı api üzerinden login olmadan hangi kullanıcının mesajlarını vereceğimizi bilemeyiz.
- Yetkilendirme - Yetkiye Göre Kısıtlama (Authorization): Yazdığımız api yi tek tip kullanıcı kullanmayabilir. Örneğin yazdığımız apiyi Free kullanıcıların ve Premium kullanıcıların kullandığını düşünelim. Bu kullanıcı tiplerine göre yetki kısıtları arttığını düşünelim. Bu durumda yetkilendirmeye ihtiyacımız olacaktır.Kısıtlama işi ise kullanıcının tahmini 1 dakikada yapacağı istek sayısı bellidir. Bu istekten çok fazlası yapılıyorsa muhtemelen bot veya türevi bir şey tarafından istekler yapılıyordur. Bu gibi durumların engellenmesi gerekiyor. Örneğin Twitter apisinde bu özellik mevcut. Bu özellik Rate limiting olarak geçiyor.
Bu konuda detaylı bilgi için: https://dev.twitter.com/docs/rate-limiting/1.1
- Sıralama / Filtreleme: Apimizden sunduğumuz veriyi her zaman aynı şekilde vermeyebiliriz. Mesela E-ticaret sitemiz var ve mobil bir uygulamamız var. Ürünleri listelediğimiz yerde mobil cihaz apiye istek yapıp ürünleri çekiyor. Kullanıcı ürünleri Fiyatını büyükten küçüğe ya da stok sayısı çoktan aza ya da tam tersini sıralayabilir. Bu durumda apide sıralama özelliğinin de olması gerekiyor. Bu örnek gibi daha bir çok örnek verilebilir.
Yine aynı örnek üzerinden gidersek kullanıcı telefondan sadece belli markaların ürünlerini ya da stokta olanları göster şeklinde ürünleri filtreleyebilir. Bu gibi durumlarda apimizde filtreleme özeliiğinin de olması gerekiyor. (Filtreleme/arama gibi özelliklerde api tarafında ElasticSearch ya da solr gibi SearchEngine leri kullanılarak güzel performans elde edilebilir.)
- Doğrulama (Validation): Yazdığımız apide her zaman kayıt listeleme işlemi yapmıyor olacağız. Örneğin yazdığımız apide kullanıcı kayıt etmek için bir api uç noktası yazdığımızı düşünelim. Kullanıcı bilgilerinin tam olarak doğru girdiğini garanti edemeyiz. Kullanıcının girdiği e-mail adresi kullanılıyor ya da belli alanları eksik girmiş olabilirler. Ya da girdiği şifre beklediğimiz şifre kriterlerinden düşük olabilir. Bu gibi durumlar için gelen verinin kontrol edilmesi gerekiyor. Veri geçerli bir veri ise kullanıcı kaydetme işleminin gerçeşmeli. Genelde kullanılan programlama dilinde hangi framework kullanılıyorsa form ile pratik bir şekilde kontrol edilmesi sağlanıyor.
- Ön Bellek (Caching): Yazdığınız api yüksek trafik alıyorsa bu gibi durumlarda aynı gelen her sorgu için veri tabanına istek yapmak yerine cache e bu veriyi yazıp veriyi buradan vermek sisteme baya bir performans katabiliyor. Bu Cacheleme yazılımsal ya da donanımsal olabiliyor. Yazılımsal olarak Redis, Memcache baya aktif kullanılıyor. Donanımsal olarak ise netscaler gibi cihazlar ile yüksek trafikteki veriler cachelenebiliyor. Bunların dışında Varnish gibi toolar ile hiç istek uygulama sunucunuza gitmeden veri cachelenebilir. (netscaler yada varnish ile apiyi cachelemeyi hiç denemedim.)
REST Neden JSON veri tipini kullanıyor ?
Yukarıda Rest ile SOAP arasındaki farklardan bahsetmiştik. SOAP imlemente etmezi zor olduğunu ve daha performanssız olduğundan bahsetmiştik. Buradaki implemente zorluğu ve performans sorununa nedenlerden biri veri tipi. JSON XML e göre daha karışık ve okuması daha zor bir veri tipidir. Diğer bir nedeni ise JSON veri tipi sadece backend değil javascript tarafında da rahat bir şekilde kullanılabiliyor. Yani yazdığımız rest apiyi javascript tarafında da aktif kullanabiliyoruz.
XML e çevirme/geri çözme işlemleri JSON a göre daha zordur. XML JSON a göre kategorize bir veri yapısına sahiptir.
JSON veri tipi XML e göre daha küçük bir veri tipidir.
REST Apilerde Dönülen HTTP Status Kodları (Yaygın Kullanılanlar)
200 OK: Genelde veri listeleme sonuçları 200 ile dönüş yapılır.
201 CREATED: Veri eklendiği zaman verinin kendisi ile 201 dönülüyor.
204 NO CONTENT: Veri silindiği zaman 204 dönülüyor.
400 BAD REQUEST: Genel olarak kayıt ekleme ya da güncelleme isteklerinde gönderilen veri validasyondan geçemediyse neden geçemediği hakkında bilgiyle beraber 400 http statusuyla dönülür.403 Forbidden: Yetkiye dayalı bir işlem yapılıyorsa bu api uç noktasında işlem yapmaya çalışan kişinin bu işlemi yapmaya yetkisi yoksa 403 status kodu döndürülür.401 Unauthorized: Api ucunuzda bu işlemi yapmak için login olmak zorunlu ise ve apiye istek yapan kullanıcı login değil ise bu http status ile cevap verilir. Örneğin kullanıcının kendi bilgilerinin güncellemesi denilebilir. 404 Not Found: Bu http status kullanıcının istek yaptığı url yok ise ya da url deki veri geçersiz ise bu hatayı alırız. örneğin şöyle bir url miz olsun /api/v1/account/bahattincinic sondaki bölüm kullanıcı adı. Buraya sistemimizde olmayan bir kullanıcı girersek 404 alırız.
405 Method Not Allowed: Bu http status u istek yapılan api uç noktası gönderilen methodu implemente etmemiş ise bu http status unu alırız. Örneğin login olması için token verdiğimiz bir api ucumuz var ve bu uçta sadece post isteğini kabul ediyor. Kullanıcı bu api urline GET isteği yaparsa bu hatayı alır.
429 Too Many Requests: Bu http statusunu saatlik ya da dakikaklık kısıtlanan sınırdan fazla istek yaparsak bu http statusunu alırız. Örnek olarak yukarıdaki Twitter örneğini vermiştik.
Bu konuyla alakalı güzel bir site :)
http://ruffledcrow.com/2012/03/06/http-status-cats/
HTTP statuslarını gruplayacak olursak;
Bilgilendirme - 1xx
Başarılı İşlem - 2xx
Yönlendirmek - 3xx
Kullanıcı Taraflı hata - 4xx
Server Taraflı hata - 5xx
