REST API URI Yapısı Nasıl Olmalı?

💡 Özet (TL;DR):
Kural 1: Kaynakları tanımlamak için fiil (/getir, /sil) değil, isim (/makaleler, /yorumlar) kullanın. HTTP metotları (GET, POST, DELETE vb.) zaten eylemi belirtir.
Kural 2: URL hiyerarşilerinde tekil değil çoğul isimleri (/kullanicilar) tercih edin. Hiyerarşiyi slash / ile kurgulayın.
Kural 3: URI sonlarında gereksiz slash (/) ve dosya uzantıları (.json) kullanmaktan kaçının.

Bu yazı, RESTful API Tasarım İncelikleri serisinin bir parçası niteliğindedir. Eğer okumadıysanız öncelikle o yazımı okumanızı tavsiye ederim.

Uç nokta (endpoint) adreslerini belirlemek için zorlayıcı bir kural yoktur. Fakat genel kabul görmüş (ve mantıklı bir temele dayanan) kurallar mevcuttur. 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 kolaylaşır; aksi takdirde API'yi kullanan birçok yazılımcı kulaklarınızı çınlatacaktır. ;)

REST API URI Doğru ve Yanlış Kullanım Örnekleri

İşlem / Durum	Yanlış / Kötü URI Tasarımı	Doğru / Standart URI Tasarımı	HTTP Metodu
Tüm Makaleleri Almak	`/api/makaleleriGetir`	`/api/makaleler`	GET
Belirli Bir Makaleyi Almak	`/api/makaleGetir/15`	`/api/makaleler/15`	GET
Makale Silmek	`/api/makaleSil/15`	`/api/makaleler/15`	DELETE
Yazının Yorumlarını Almak	`/api/makale/15/yorumlarigetir`	`/api/makaleler/15/yorumlar`	GET
Dosya Formatı Belirtmek	`/api/makaleler.json`	`/api/makaleler` (Accept Header ile)	GET

Serinin Tamamı

1. Kaynakları Tanımlamak İçin İsim Kullanın

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

Örneğin, bir blogdaki makaleleri gösteren bir uç nokta için https://ornekadres.com/api/makaleleri-getir adresi yerine https://ornekadres.com/api/makaleler adresini tercih edin.

Bu şekilde URL'deki uç nokta bir nesneyi temsil ederken, HTTP metodunuz da eylemi 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/makaleler/15 adresine bir DELETE isteği göndererek aynı işlemi gerçekleştirebilirsiniz.

2. Tekil Değil Çoğul İsimler Tercih Edin

Genel olarak "makale" tek bir kaynak, "makaleler" ise kaynaklardan oluşan bir koleksiyondur. Uç nokta adreslerinde koleksiyon isimleri (çoğul) 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. JSON API spesifikasyonu da çoğul isimlerin kullanılmasını önermektedir.

3. Kaynakların Alt Koleksiyonları (Sub-collections)

Belirli bir kaynağa ait ilişkili alt verileri sorgulamak için hiyerarşik URI yapıları kurulur. Örneğin, belirli bir makaleye gelen yorumları sorgulamak için ornekadres.com/makaleler/{makaleId}/yorumlar adresine istek gönderebiliriz.

4. Standartlara ve Kurallara Bağlı Kalın

Genel kabul görmüş kuralları kullanmak istemeyebilirsiniz; ancak kuralınız ne olursa olsun API'nin her yerinde aynı standardı benimsemelisiniz. Genel kabul görmüş ve JSON API tarafından da belirlenen kurallardan bazıları şunlardır:

Hiyerarşik ilişkileri tanımlamak için slash (/) karakterini kullanın:
Slash karakteri (/) adreslerde hiyerarşik bağlantıları belirlemek için kullanılır. Eğer hiyerarşiyi slash yerine alt çizgi ile sağlayacaksanız (örneğin makale_15_yorumlar), API'nin her yerinde bu kuralı uygulayın.
Slash kullanılan standart örnekler:
- https://ornekadres.com/blog-yonetimi/makaleler
- https://ornekadres.com/blog-yonetimi/makaleler/{makaleId}
- https://ornekadres.com/blog-yonetimi/makaleler/{makaleId}/yorumlar
- https://ornekadres.com/blog-yonetimi/makaleler/{makaleId}/yorumlar/{yorumId}
URI'lerin sonunda gereksiz slash kullanmayın:
Adresin sonuna ekleyeceğiniz / karakterinin hiçbir anlamı yoktur ve sistemler arası uyumsuzluklara neden olabilir.
- Kötü kullanım: https://ornekadres.com/blog-yonetimi/makaleler/
- İyi kullanım: https://ornekadres.com/blog-yonetimi/makaleler
Okunabilirliğin artırılması (Kelime Ayrımı):
JSON API, kaynak isimleri birden fazla kelimeden oluşuyorsa bunları CamelCase olarak ayırmamızı önerir:
https://ornekadres.com/kullanicilar/15/cihazAyrintilari
Fakat URL standartlarında çizgi (-) karakteri (kebab-case) daha yaygın kabul görür ve SEO dostudur:
https://ornekadres.com/kullanicilar/15/cihaz-ayrintilari
Küçük harf kullanımı:
RFC 3986, URI'leri alan adı dışındaki yollarda büyük-küçük harf duyarlı olarak tanımlar. Karışıklığı önlemek adına her zaman küçük harf standardını benimseyin.
Dosya uzantısı kullanmayın:
Dosya uzantıları kötü göründüğü gibi hiçbir işlevleri de yoktur. Yanıtın medya türünü (Content-Type) belirlemek istiyorsanız, bunu dosya uzantısı ile değil, HTTP başlığındaki (Header) Accept ve Content-Type değerleri ile yapmalısınız:
- Kötü: https://ornekadres.com/kullanicilar/15/cihazAyrintilari.json
- İyi: https://ornekadres.com/kullanicilar/15/cihazAyrintilari
Unicode Karakterler:
URI'lerde ve JSON anahtarlarında sadece şu güvenli ASCII karakter aralıklarını kullanmalısınız:
- a-z (U+0061 ile U+007A arası)
- A-Z (U+0041 ile U+005A arası)
- 0-9 (U+0030 ile U+0039 arası)
- Çizgi - ve Alt Çizgi _
  URL güvenli olmayan boşluk (space) veya Türkçe/Unicode karakterlerin URI'lerde doğrudan kullanımı sunucu hatalarına yol açabilir.

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

Uç nokta adresleri hakkında şimdilik paylaşacaklarım bu kadar. Aklıma geldikçe yeni pratikleri ekleyeceğim. Siz de sorularınız veya eklemek istedikleriniz varsa yorumlar bölümünden paylaşabilirsiniz.

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.

Bu Yazıda Yapılan Değişiklikler

11.05.2022: Yazı özeti düzenlendi.
21.06.2026: Türkçe imla ve yazım hataları (hiyerarşiyi, gereksiz, standarda, duyarlı vb.) düzeltildi. URL sonlarındaki geçersiz boşluk karakterleri kaldırıldı. TL;DR özet paneli ve doğru/yanlış URI tasarımlarını gösteren karşılaştırma tablosu eklenerek yazı zenginleştirildi.