RESTful API Tasarlama – Best Practices

Facebook, Google, Amazon, Github gibi pek çok teknoloji devi geliştiricilere ürünlerini ve verilerini API’ler aracılığıyla kullanma şansı veriyor.  Biz de kendi projelerimizi geliştirirken bu API’leri kullanıyoruz. Ya da kendi projelerimizde API endpointlerimiz oluyor. Kısa bir giriş yaptıktan sonra esas meselemize gelelim. Nedir bu RESTful APİ?

1)REST(Representional State Transfer)

Basitçe client-server arasındaki haberleşmeyi sağlayan mimaridir. REST mimarisini kullanan servislere RESTful servis denir. Belki bir çoğunuzun aklına zaten bu veri alış-verişini sağlayan SOAP gibi mimariler mevcut neden SOAP vb. mimariler yerine REST’i tercih etmeliyim gibi sorular gelmiş olabilir. SOAP gibi mimariler günümüzde çok kompleks kalıyor. REST ise HTTP protokolü üzerinden çalışan bir mimaridir. RESTful servisler ile çok farklı şekillerde response alabiliriz. Popüler olarak JSON kullanılsa da XML, CSV gibi türlerde de response alınabilir.

2) API endpointleri

Kendi projemde yazdığım bir endpointten örnek vermek istiyorum. Kullanıcı ile ilgili işlemleri yaptığımız bir endpoint var peki bunu nasıl tasarlamalıyım?

• /addUser
• /updateUser
• /deleteUser
• /showUser
• /showAllUser

Yukarıda verdiğim örnekte kullanıcısı datası üzerinde işlem yapmak için bir sürü endpoint açmam gerekti. API sayısı arttıkça işler daha da karmaşık hale gelecekti. Bu çok efektif bir yaklaşım değil. Peki bu kullanıcı endpointini nasıl yaratmalıyım?

• URL, sadece ve sadece isimleri içermelidir. Yukarıdaki add, update, delete, show gibi kelimeler olmamalı /Users

Tamam, URL ve ismi hallettik. Peki biz bu API’ye işlemleri nasıl yaptıracağız. İşte tam bu noktada HTTP metotları(GET, POST, DELETE, PUT) rol oynuyor.

• metot GET /Users => tüm kullanıcıları getirir
• metot GET /Users/1 => id’si 1 olan kullanıcıyı getir
• metot DELETE /Users/1 => id’si 1 olan kullanıcıyi sil

Bu aşamaya kadar yazıyı okumaya devam ettiyseniz artık daha tutarlı(consistent) APİ’ler yazmaya başlayabilirsiniz.

Özet: pathlerimiz sadece ve sadece isimlerden oluşmalıdır. HTTP metotları ile bu isimler üzerinde gerçekleştirilecek eylem türleri kullanılmalıdır.

3. HTTP Metotları ve Durum Kodları

4 temel metodumuz var.

Durum kodlarımız ise;

• 1XX ile başlayan kodlar bilgi amaçlı kodlardır.
• 2XX ile başlayan kodlar başarı kodlarıdır.
• 3XX ile başlayan kodlar yönlendirme kodlarıdır.
• 4XX ile başlayan kodlar ise client(istemci) hatası kodlarıdır.
• 5XX ile başlayan kodlar ise server(sunucu) hatası kodlarıdır.

4) Arama, sıralama, filtreleme ve sayfalama

• Sıralama Eğer client kullanıcı bilgilerini yaşa göre sıralı bir şekilde almak isterse, GET /Users endpointine bir sıralama parametresi eklemeliyiz. GET /Users?sort=age_asc gibi…
• Filtreleme Eğer client kullanıcı bilgilerini ülke veya dil bazında filtrelemek isterse şu tip bir yapı kurulabilir. GET /Users?location=turkey
• Arama Eğer client kullanıcı bilgilerinde id’ye göre değil de direk isme göre arama yapmak isterse şu tip bir yapı kurulabilir. GET /Users?searcName=erkan liman
• Sayfalama(pagination) client tarafında özellikle mobil cihazlarda tüm kullanıcı datasını ya da iki kullanıcının mesajlaşmalarını tek bir seferde getirmeye çalışırsak memory muhtemelen yetmeyecektir. Bu yüzden dataları sayfalamamız gerekir. GET /User?page=10

5) API Versiyonlama

Production ortamındaki bir endpointinize yeni özellikler kattığınızda ya da bazı özellikleri kapattığınızda bunun client tarafında güncellenmesi epey zaman alabilir ya da hiç güncellenmeyebilir. Bu yüzden direk production’da endpointi etkilememiz lazım. Bunun en efektif yolu ise versiyonlamadır. Eğer ben www.apidemo.com/Users şeklinde bir tasarım yaptıysam bu direk client tarafında patlamama sebep olur. www.apidemo.com/v1/Users şeklinde bir tasarım yapmalıyım. Yeni özellikleri ise www.apidemo.com/v2/Users şeklinde çıkmalıyım.