REST API URI yapısı nasıl olmalı?

Bu yazı RESTFul Api Tasarım İncelikleri serisinin bir parçası niteliğindedir. Eğer okumadıysanız öncellikle o yazımı okumanızı tavsiye ederim.

REST API tasarım incelikleri

Uç nokta adreslerini belirlemek için zorlayıcı bir kural yok. Fakat genel kabul görmüş (ve bir mantığa dayanan) kurallar var. Eğer adresleri belirli bir standart ve mantık çerçevesinde oluşturursanız API’yi dokümante etmeniz ve kullanıcıların öğrenmesi daha kolay olur, aksi takdirde API’yi kullanan bir çok yazılımcı kulaklarınızı çınlatacaktır. 😉

Serinin Tamamı

Kaynakları tanımlamak için isim kullanın

Uç nokta adreslerimizde fiil (yüklem) değil isim kullanmalıyız. Bu isim bilgi almaya veya işlem yapmaya çalıştığımız nesne neyse o olmalı.

Örneğin bir blogdaki makaleleri gösteren bir uç noktası için https://ornekadres.com/api/makalelerigetir/ adresi yerine https://ornekadres.com/api/makaleler adresini tercih edin.

Bu şekilde URL’deki uç nokta bir nesneyi temsil ederken, HTTP metodunuzda bir yüklemi temsil edecektir. GET->Getir, DELETE->Sil, PATCH->Düzelt gibi.

Adresleri bu şekilde belirlerseniz; örneğin makale silmek için …/api/makalesil/15 adresine bir GET isteği değil ../api/makale/15 adresine bir DELETE isteği göndererek aynı işlemi gerçekleştirebilirsiniz.

Tekil değil çoğul isimler

Genel olarak “makale” bir kaynak “makaleler” ise kaynaklardan oluşan bir koleksiyondur. Uç nokta adreslerinde yalnızca koleksiyon isimleri kullanmanız daha doğru bir seçim olur. Böylece ornekadres.com/makaleler/ adresine bir GET isteği göndererek tüm makaleleri sorgulayabilir veya ornekadres.com/makaleler/{makaleId} adresine göndereceğiniz GET isteği ile belirli bir makaleyi sorgulayabilirsiniz. (Silebilirsiniz, güncelleyebilirsiniz vs. vs.) JSON API spesifikasyonu da çoğul isimlerin kullanılmasını öneriyor.

Bir kaynağın alt koleksiyonları olabilir

Örneğin belirli bir makaleye gelen yorumları sorgulamak için ornekadres.com/makaleler/{makaleId}/yorumlar/ adresine istek gönderebiliriz.

Kurallarınız net olsun

Genel kabul görmüş kuralları kullanmak istemeyebilirsiniz. Ama kuralınız her ne olacaksa API’nin her yerinde aynı kuralı benimsemelisiniz.
Genel kabul görmüş ve JSON API tarafından da belirlenen kurallar olmaları nedeniyle aşağıdakileri referans alabilirsiniz.

Hiyerarşik ilişkileri tanımlamak için slash (eğik çizgi) karakterini kullanın
Slash karakteri (/) adreslerde hiyerarşik bağlantıları belirlemek için kullanılır. Siz hiyearşiyi slash yerine alt çizgi ile (örneğin makale_15_yorumlar) sağlayacaksanız API’nin her yerinde bu kuralı uygulayın.
Slash kullanılan örnekler; https://ornekadres.com/blog-yonetimi/makaleler https://ornekadres.com/blog-yonetimi/makaleler/{makaleId} https://ornekadres.com/blog-yonetimi/makaleler/{makaleId}/yorumlar ornekadresi.com/blog-yonetimi /makaleler/{makaleId}/yorumlar/{yorumId}
URI’lerin sonunda gerekssiz slash kullanmayın
Adresin sonuna ekleyeceğiniz slash karakterinin hiç bir anlamı yoktur ve karışıklığa neden olabilir. En iyisi hiç kullanmamaktır.
https://ornekadres.com/blog-yonetimi/makaleler/ https://ornekadres.com/blog-yonetimi/makaleler /* Bu örnek çok daha iyi */
Okunabilirliğin arttırılması
JSON API kaynak isimleri birden fazla kelimden oluşuyorsa bunları Camel-Case olarak ayırmamızı öneriyor.
Örn. https://ornekadres.com/kullanicilar/15/cihazAyrintilari gibi
Fakat yine Json API tanımlarında çizgi ( – ) karakterine izin verildiği için tercih edilmese de standarta aykırı olmayacaktır.
Örn. https://ornekadres.com/kullanicilar/15/cihaz-ayrintilari
Küçük harf kullanımı
RFC 3986 URI’leri şema ve alan adı dışında büyük-küçük harf duyarılı olarak tanımlıyor. Genelde küçük harf kullanıyor olsa da, önemli olan bir standart belirlemeniz ve her yerde onu kullanmanızdır.
Dosya uzantısı kullanmayın
Dosya uzantıları kötü göründüğü gibi hiç bir işlevleri de yoktur. Eğer yanıtın medya türünü belirlemek istiyorsanız bunu dosya uzantısı ile değil (ki aslında dosya uzantısı bunu yapmaz) sunucu cevap başlığındaki Content-Type ile yapmalısınız.
https://ornekadres.com/kullanicilar/15/cihazAyrintilari.json
yerine
https://ornekadres.com/kullanicilar/15/cihazAyrintilari
adresini kullanmayı tercih edin.
UNICODE karakterler
Sadece URI’lerde değil, JSON anahtar tanımlarınız içinde sadece aşağıdaki karakter aralıklarını kullanmalısınız.
U+0061 ile U+007A arası, “a-z”
U+0041 ile U+005A arası, “A-Z”
U+0030 ile U+0039 arası, “0-9”
Ek olarak aşağıdaki karakterleri de kullanabilirsiniz.
U+002D ÇİZGİ, “-“
U+005F ALT ÇİZG, “_”
U+0080 ve üzeri URL güvenli olmadığı için önerilmemektedir.
U+0020 BOŞLUK, “ ” URL güvenli olmadığı için önerilmemektedir.

Daha ayrıntılı bilgi için JSON API dokümanını inceleyebilirsiniz.

Uç nokta adresi – URI hakkında şu an yazabileceklerim bu kadar. Aklıma geldikçe yeni bilgiler ekleyeceğim, siz de yorumlar bölümünü kullanarak ekleme yaparsanız memnun olurum.

Bir sonraki bölümde kimlik doğrulama konusunu işleyeceğiz, ama öncesinde bu diziye sonradan ilave ettiğim HATEOAS kavramını okumanızı tavsiye ederim.