REST API tasarım incelikleri

RESTful API tasarımının inceliklerini öğrenmeye kimin ihtiyacı var? Bu yazı kimin için?

Tek tabanca bir geliştirici ve küçük orta büyüklükte bir web sitesi oluşturuyorsan bir RESTApi’ye ihtiyacın olmayacak, bildiğin yöntemle devam edebilirsin.

Fakat web sitesinin, mobil cihazların, belki diğer web sitelerinin tüketici olacağı bir backend tasarlaman gerekiyorsa o zaman REST API tasarımın inceliklerini öğrenmen gerekiyor.

Konunun genişliğini ve benim de uzun uzun yazmayı seven bir insan olduğumu göz önüne alırsan konuyu parçalara ayırarak işlemem daha kolay olacaktır.

Bu yazı RESTFul API’lerle ilgili şu bölümleri içerecek

Aşağıdaki başlıklar altında birden fazla yazı yazmayı düşünüyorum. İlk iki başlık bu yazı içerisinde yer alıyor olacak, diğerleri ile ilgili ayrı yazılar yazıp tamamlandıkça buradan bağlantı vereceğim.

Dürüst olacağım, bu bilgilerin çoğunun kaynağı ben değilim. 1-2 sene öncesine kadar API’lerin sadece tüketicisiydim. Gün gelip bir Api yazmam gerektiğinde bu konuda bol bol araştırma yapıp notlar aldım ve bu yazacaklarım o notlarımın derlenip toplanmış, biraz da kendimden bir şeyler katılmış hali.

Çoğunluğu bir Word dosyası içine sağdan yoldan yapıştırılan şeyler olduğu için net bir kaynak veremeyeceğim ama zaten çoğu “aklın yolu bir” denecek açıklamalar 2+2=4 için referans aramaya çok da gerek yok.

Farklı Yaklaşımlar

Burada anlatacağım başlıkların çoğu için farklı yaklaşımlar veya yöntemler olabilir. Hatta piyasadaki devleri incelediğinizde burada anlatılanlarla uyumsuz noktalar olduğunu, kendi standartlarını benimsediklerini görebilirsiniz. Benim anlatacaklarım; yaptığım araştırmalar ve denemeler sonrasında aklımda yer eden, “ben bir REST Api tasarlasam böyle yaparım” dediğim yöntemler olacak.

Teknoloji ve Alt Yapı

Teknoloji ve alt yapı API tasarımının dışında, kaynaklar, ihtiyaçlar ve (mevcut bir sisteme entegrasyon konusuysa) mimari ile ilgili bir durum. O nedenle işin sunucu, yazılım vs. kısmını atlayıp doğrudan API tasarımını ilgilendiren bölümlerine geçeceğim. .

Daha önce yazdığım RESTful API bileşenleri başlığında bu konudaki kişisel tercihlerimi belirtmiştim.

RESTful API bileşenleri

REST API Temelleri

RESTful API tasarımı ile belirli kaynaklar sunup bunları tüketici/istemcinin kullanımına açmış oluyorsunuz. Hani tek tabanca sitelerde AJAX ile backend’imize sorgu atıyor ve gelen sonuçlara göre istemci işlemler yapıyor veya bir şeyler gösteriyoruz ya, işte RestFul API herhangi bir istemcinin bize Ajax ile istek göndermesi, bizim de o istemcinin anlayacağı standart bir dille cevap vermemiz diyebiliriz.

API’niz kaynaklar (örneğin yazar) veya bu kaynaklardan oluşan koleksiyonları (yazarlar) paylaşıma açıyor, oluşturuyor, güncelliyor ve benzeri işlemleri gerçekleştiriyor.

Bu kaynaklarla işlem yapmak için önceden belirlenmiş uç nokta adresleri GET, POST, PUT, PATCH ve DELETE gibi klasik HTTP metodları ile veri alışverişi yapıyorsunuz.

Aslına bakarsanız keşke her proje sadece RESTful API’den oluşsa. Standart bir veri gelecek, o standart veriyle işlem yapıp, standart bir formatta çıktı vereceksiniz, var mı yazılımcı için daha rahatı. 🙂 Full-stack bir uygulama geliştirmekten çok daha kolay değil mi?

Çıktı Formatı Ne Olmalı?

API’nızın çıktı formatı JSON, CSV, XML, RSS, HTML veya ihtiyacınız olan herhangi bir format olabilir. İhtiyaçların sınırsız olduğu dünyada şüphesiz bunlara yönelik çözümler de sınırsız. Fakat genel kullanıma açık bir Rest API tasarlıyorsanız muhtemelen JSON ya da XML (Genellikle JSON) seçeceksiniz.

Ben sizin yerinizde olsam zorlayıcı özel bir bir sebep yoksa çıktı formatı olarak JSON kullanmayı tercih ederdim.

Takip eden bölümde RESTful API’lerde Uç Nokta Adresleri – Endpoint URL’ler nasıl belirlenmeli bu konuda üzerinde duracağım.