Oluşturduğumuz bir uygulamanın erişilebilir olması için bir arayüz tasarlamamız gerekli. Bu arayüze gelecek HTTP istekleri ile uygulamamızın verileri erişilebilir olacaktır. Bu arayüzü bağlantılarını tasarlarken dikkat etmemiz gereken bazı noktaları aşağıda listeleyeceğim.
Versiyonlama
Bağlantılarımıza versiyon bilgisi eklemek uzun vadede geçişleri kolaylaştıracak bir pratik olacaktır. Aynı zamanda kullanıcılara da eski versiyonda kalabilmeleri esnekliğini sağlayacaktır.
../v1/users
../v2/usersFiil Kullanımında Kaçın / İsim Kullanmaya Çalış
Bağlantımızda her kelime anlamlı bir veriye işaret etmeli. Fakat bu veri ismini yanına ilgili işlemi belirten bir fiil koymak kullanışsız olur.
Bu eylemleri HTTP metotları ile belirtebiliriz. Bildiğiniz gibi HTTP içerisinde en çok kullanılan metotlar GET, POST, PUT, DELETE yeterli olacaktır. Şurada ve şurada bu eylemler hakkında detaylı bilgi var.
Türkçe bir kaç örnek verelim.
../haberleriGetir şeklinde bir bağlantı yerine ../haberler bağlantısına yapılacak bir GET isteği daha sade ve anlamlı olacaktır.
../haberOlustur yerine ../haberler bağlantısına yapılacak POST isteği ile yeni bir haber oluşturulabilir.
../haberiGuncelle yerine ../haberler/123 bağlantısına yapılacak PUT isteği ile 123 ID’li haber güncellenebilir.
Tekil – Çoğul Karışıklığından Kaçın
Bir varlık için kullandığımız ismin çoğul halini kullanarak daha sade ve anlamlı bir tasarım yapmış oluruz.
Yine Türkçe bir örnek verelim;
| ../kisiler | kayıtlı tüm kişileri bir dizi halinde döner. |
| ../kisiler/5 | kayıtlı kişilerin içinden 5 ID’li kişinin bilgilerini döner |
| ../kisi/5 | kullanılmamalıdır. Varlık olarak kişiler adını verdiğimiz verilere şimdi kişi adını vermiş olduk. |
Filtreleme, Sıralama, Sayfalama ve Süzme
Bu işlemler için bağlantı içerisinde bir yer ayırmaktansa query parametresi olarak kabul etmeliyiz. Bağlantı içerisine eklemeye çalışırsak orta karmaşıklıktaki veriler için bile onlarca ihtimal oluşacaktır. İçinden çıkılmaz bir hal alır. Bunun yerine bu işlemler için gerekli bilgileri parametre olarak alabiliriz.
| ../haberler?tarih=bugun | Sadece bugüne ait haberler için bir filtreleme ekledik |
| ../haberler?siralama_yonu=-1&siralama_tipi=tarih ../haberler?sirala=tarih:-1 | Tarihe göre ters sıralama yapılması için iki örnek |
| ../haberler?sayfa=5 | 5. sayfadaki haberler |
| ../haberler?bilgi=baslik,tarih | Gelen veride sadece başlık ve tarihin olması için bir süzme talebi |
Bağlı Veriler için İç İçe Bağlantılar Oluştur
Varlıklarımız onlara bağlı pek çok başka varlıklar içerecektir. Bunları sunarken hiyerarşik yapıya uygun olarak ve iki varlık arasında ilişkiyi gözeterek bir bağlantı metni oluşturmamız gerekir.
Haberler örneğinden devam edelim ve haberimize bağlı yorumları getirelim.
| ../haberler/5/yorumlar | 5 ID’li habere ait tüm yorumları listeler |
| ../haberler/5/yorumlar/3 | 3 ID’li yorumu döner. Bu yorum 5 ID’li habere aittir. |
| ../yorumlar/3/haber/5 | Kullanılmamalıdır. Hiyerarşik olarak bir yorum bir habere bağlıdır ve bu haber için ID belirtilmesine gerek yoktur. |
| ../haberler/yorumlar/3/5 | Kullanılmamalıdır. Hangi veri hangi varlığa ait anlaşılmaz. |
Diğer Konular
- SSL kullanımı önemli, isteklerin araya girerek dinlenmesine engel olabilirsiniz.
- Dil olarak İngilizce kullanımı en uygunu olacaktır. Örneklerde anlaşılması için Türkçe kullandım fakat hem karakter destek sorunları hem de global olması sebebiyle İngilizce her zaman daha anlamlı olacaktır.
- Farklı içerik tiplerinde (JSON, text, binary…) dönüşler yapılacaksa bunları content-type headerı içinde alıp ona göre işlem yapabilirsiniz. Dönüş tipi için bağlantı metninde değişiklik yapmanız gerekmez.
- Kullanıcıyı tanımamızı sağlayan bilgiyi (token) URL içerisinde kabul edilmemeli. Header içinde Authorization verisi olan alınmalı.