DEV Community

Cover image for REST API İsimlendirme Kuralları: Uygulamalı Stil Rehberi
Tobias Hoffmann
Tobias Hoffmann

Posted on Originally published at apidog.com

REST API İsimlendirme Kuralları: Uygulamalı Stil Rehberi

İki yıldan eski herhangi bir kod tabanını açın ve izleri bulacaksınız: /getUser, /user_list, `[REDACTED PATH]

{% cta https://apidog.com/?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation %} Apidog'u bugün deneyin {% endcta %}

İsimlendirme, API tasarımındaki en ucuz kararlardan biri; değiştirilmesi ise en pahalı olanıdır. Müşteriler /getOrders uç noktasına bağlandığında, onu yıllarca desteklemeniz gerekir.

Bu kılavuz, REST API tasarlarken karşılaşacağınız isimlendirme kararları için uygulanabilir kurallar sunar. Her kuralda doğru ve yanlış örnekleri göreceksiniz. Yaklaşım, geliştiriciler için REST API yönergelerimiz ile aynıdır; ancak odağı, ekiplerin en çok tartıştığı konuya verir: şeylere ne isim verileceği.

Kod incelemelerinde aynı yorumları tekrar etmek yerine bu kuralları tasarım aşamasında uygulamak isterseniz, Apidog ile her uç noktayı ortak bir şema üzerinden görsel olarak tanımlayabilirsiniz.

Koleksiyonlar için çoğul isimler kullanın

URL bir işlemi değil, kaynağı adlandırır. Koleksiyonlar nesne kümeleridir; bu nedenle çoğul isim kullanın.

Yapın:

http
GET /v1/products
GET /v1/products/89
GET /v1/orders

Yapmayın:

http
GET /v1/getProducts
GET /v1/product
GET /v1/productList

Çoğul form her iki seviyede de doğal okunur:

  • /products: ürün koleksiyonu
  • /products/89: koleksiyondaki 89 numaralı ürün

Tekil adlandırma, /product/89 gibi tutarsız URL'lere yol açar. Microsoft REST API yönergeleri bu nedenle çoğul isimleri önerir; Stripe, GitHub ve Shopify gibi genel API'ler de aynı yaklaşımı kullanır.

İstisna: Tekil kaynaklar. Kullanıcının tam olarak bir sepeti varsa `[REDACTED PATH]mayın.

Yollardan fiilleri çıkarın

HTTP metodu zaten fiildir. URL'ye ayrıca fiil eklemek gereksiz tekrar yaratır ve kaynak modelini bozar.

Yapın:

GET    /v1/orders/42      # oku
DELETE /v1/orders/42      # sil
PATCH  /v1/orders/42      # güncelle
Enter fullscreen mode Exit fullscreen mode

Yapmayın:

GET  /v1/fetchOrder/42
POST /v1/deleteOrder/42
POST /v1/updateOrderStatus
Enter fullscreen mode Exit fullscreen mode

Fiil tabanlı yollar API yüzeyini büyütür. Dört HTTP metodu olan tek bir kaynak, ayrı ayrı belgelenecek, test edilecek ve önbelleğe alınacak dört farklı URL'ye dönüşür.

Kaynak URL'sini korumak önbellek geçersiz kılmayı da kolaylaştırır. CDN, GET /v1/orders/42 yanıtını önbelleğe alıp aynı URL'ye yönelik DELETE isteğinde geçersiz kılabilir. /fetchOrder/42 ile /deleteOrder/42 arasında bu ilişkiyi kuramaz.

URL yollarında kebab-case kullanın

Çok kelimeli yol segmentlerinde ayırıcı olarak tire kullanın.

Yapın:

/v1/gift-cards
/v1/shipping-addresses
Enter fullscreen mode Exit fullscreen mode

Yapmayın:

/v1/giftCards
/v1/gift_cards
/v1/GiftCards
Enter fullscreen mode Exit fullscreen mode

Bunun üç temel nedeni vardır:

  1. Google, tireleri kelime ayırıcı olarak kabul eder.
  2. Alt çizgiler, URL'ler e-postalarda veya belgelerde altı çizili gösterildiğinde kaybolabilir.
  3. CamelCase, büyük/küçük harf hatalarına açıktır. /giftCards ve /giftcards çoğu sunucuda farklı URL'lerdir.

Zalando RESTful API yönergeleri kebab-case kullanımını zorunlu kılar.

JSON alan adlarında tek bir stil seçin

camelCase ve snake_case'in ikisi de çalışır. Sorun, ikisini aynı API içinde karıştırmaktır.

Tutarlı bir stil seçin:

{
  "orderId": 42,
  "createdAt": "2026-08-30T09:15:00Z",
  "totalAmount": 4999
}
Enter fullscreen mode Exit fullscreen mode

veya:

{
  "order_id": 42,
  "created_at": "2026-08-30T09:15:00Z",
  "total_amount": 4999
}
Enter fullscreen mode Exit fullscreen mode

Yapmayın:

{
  "orderId": 42,
  "created_at": "2026-08-30T09:15:00Z",
  "TotalAmount": 4999
}
Enter fullscreen mode Exit fullscreen mode

camelCase, JavaScript ve Java istemcileriyle doğal biçimde eşleşir. snake_case ise daha okunaklıdır ve Ruby, Python ve çoğu SQL sütun adıyla uyumludur; Stripe da bu stili her yerde kullanır.

API'nizi en çok kimin kullandığına göre seçim yapın ve bunu stil rehberinize yazın. Şema incelemelerinde aynı kuralı uygulayın. Karma adlandırma genellikle bir zevk meselesi değil, ekipler arası yönetişim eksikliğidir.

İç içe geçirmeyi iki seviyede sınırlayın

İç içe geçirme sahipliği ifade eder:

[REDACTED PATH]
Enter fullscreen mode Exit fullscreen mode

Bu URL, 42 numaralı kullanıcıya ait siparişleri belirtir. Ancak iki seviyeden sonra URL hızla kullanışsızlaşır.

Yapın:

GET /v1[REDACTED PATH]
GET /v1/orders/1337/refunds
Enter fullscreen mode Exit fullscreen mode

Yapmayın:

GET /v1[REDACTED PATH]
Enter fullscreen mode Exit fullscreen mode

Derin iç içe geçirme, yaprak kaynağın küresel olarak benzersiz kimliği olsa bile istemcileri tüm üst kaynak kimliklerini taşımaya zorlar.

Geri ödemenin kimliği 7 ise şu seçeneklerden biri yeterlidir:

GET /v1/refunds/7
GET /v1/orders/1337/refunds/7
Enter fullscreen mode Exit fullscreen mode

İyi bir koku testi: URL üç veya daha fazla kimlik içeriyorsa onu düzleştirin. Sipariş oluşturulduktan sonra /orders/1337 için kullanıcı kimliğine ihtiyaç yoktur.

Filtreleme, sıralama ve sayfalama için sorgu parametreleri kullanın

Yollar kaynakları tanımlar. Sorgu parametreleri, kaynakların nasıl görüntüleneceğini belirtir.

Yapın:

GET /v1/orders?status=active&sort=-created_at&limit=50&cursor=eyJpZCI6NDJ9
GET /v1/products?category=electronics&min_price=1000
Enter fullscreen mode Exit fullscreen mode

Yapmayın:

GET /v1/orders/active
GET /v1/orders/sorted-by-date-desc
GET /v1/getOrdersByStatusAndDate
Enter fullscreen mode Exit fullscreen mode

sort=-created_at biçimi, azalan sıralama için eksi ön eki kullanır ve ayrı bir order=desc parametresi ihtiyacını ortadan kaldırır.

/orders/active gibi filtre yolları başlangıçta basit görünür. Ancak filtreleri birleştirdiğinizde her kombinasyon için yeni uç noktalar üretmeniz gerekir.

Sayfalama parametrelerinde de tek bir yaklaşım seçin:

  • limit / cursor
  • page / per_page

Seçtiğiniz adları tüm koleksiyonlarda yeniden kullanın. İmleç ve ofset tabanlı yaklaşımların karşılaştırması için API sayfalama kılavuzumuza bakabilirsiniz.

Sürümü URL yolunda belirtin

Yaygın iki seçenek vardır:

GET /v1/products
Enter fullscreen mode Exit fullscreen mode

veya:

Accept: application/vnd.myapi.v1+json
Enter fullscreen mode Exit fullscreen mode

Başlık tabanlı sürümleme daha “saf” bir REST yaklaşımıdır. URL, sürümler arasında aynı kaynağı adlandırmaya devam eder. Google API tasarım rehberliği de her iki yöntemin yaygın olduğunu belirtir.

Buna rağmen URL sürümleme operasyonel açıdan daha pratiktir:

  • Günlüklerde açıkça görünür.
  • Tarayıcıdan ve curl ile kolayca test edilir.
  • Vary karmaşası olmadan önbelleğe alınabilir.
  • İstemcinin sürüm başlığını eklemeyi unutması mümkün değildir.

Yalnızca ana sürüm numarası kullanın:

/v1/products
Enter fullscreen mode Exit fullscreen mode

Şunu kullanmayın:

/v1.2/products
Enter fullscreen mode Exit fullscreen mode

Küçük sürümler geriye dönük uyumlu ve bozucu olmayan değişiklikler olarak yayınlanmalıdır. İçerik anlaşması da dahil olmak üzere seçenekleri karşılaştırmak için API sürümleme stratejileri yazımıza bakın.

Kaynak kimliklerini opak tutun

Şu URL'ler fazla bilgi sızdırır:

/orders/41
/orders/42
/orders/43
Enter fullscreen mode Exit fullscreen mode

Sıralı tam sayılar, işlenen sipariş sayısını açığa çıkarır ve saldırganların kimlik alanını tarayarak yetkilendirme açıklarını aramasını kolaylaştırır. Bozuk nesne seviyesi yetkilendirme, OWASP API Security Top 10 listesinin ilk sırasında yer alır.

Yapın:

GET /v1/orders/ord_9f8e2a71b3
GET /v1[REDACTED PATH]
Enter fullscreen mode Exit fullscreen mode

Numaralandırılabilir kimlikleri dışarı açmayın:

GET /v1/orders/42
GET /v1/invoices/10883
Enter fullscreen mode Exit fullscreen mode

Stripe'ın ord_9f8e2a71b3 gibi ön ekli rastgele kimlikleri güçlü bir seçenektir:

  • Tahmin edilmeleri zordur.
  • Günlüklerde açıklayıcıdır.
  • URL'de paylaşılmaları daha güvenlidir.

Opak kimlikler yetkilendirme kontrollerinin yerini tutmaz. Dahili veritabanında tam sayı birincil anahtar kullanmaya devam edebilirsiniz; kural, URL'de neyi açığa çıkardığınızla ilgilidir.

CRUD dışı eylemleri denetleyici kaynakları olarak modelleyin

Her API'de standart CRUD işlemlerine sığmayan eylemler bulunur:

  • Siparişi iptal etme
  • Ödemeyi yeniden deneme
  • E-postayı yeniden gönderme

Bu eylemleri üst seviyede fiil olarak tanımlamayın veya durum alanı güncellemesine gizlemeyin.

Yapın:

POST /v1/orders/42/cancel
POST /v1/payments/pay_88a1/retry
Enter fullscreen mode Exit fullscreen mode

Yapmayın:

PATCH /v1/orders/42
{ "status": "cancelled" }

POST /v1/cancelOrder
{ "orderId": 42 }
Enter fullscreen mode Exit fullscreen mode

Bu, fiilsiz URL kuralının kontrollü istisnasıdır. Fiil, üzerinde işlem yapılan kaynağın altında ve yolun sonunda yer alır.

Bir siparişi iptal etmek; para iadesini tetiklemek, envanteri serbest bırakmak ve bildirim göndermek gibi yan etkilere sahip olabilir. Bu nedenle işlemi sıradan bir alan güncellemesi gibi modellemek yanıltıcıdır.

/cancel gibi bir uç nokta:

  • İşlemin amacını açıkça belirtir.
  • Ayrı izinler ve denetim kayıtları tanımlamanızı sağlar.
  • İptal nedeni gibi eyleme özgü girdiler için alan bırakır.

Başlık ve sorgu parametrelerinde adlandırmayı tutarlı tutun

Özel başlıklarda HTTP geleneğine uygun olarak Hyphenated-Pascal-Case kullanın:

Idempotency-Key
Request-Id
Enter fullscreen mode Exit fullscreen mode

Eski X- ön ekini kullanmayın; bu yaklaşım RFC 6648 ile 2012'de kullanım dışı bırakıldı. HTTP başlıkları ağ üzerinde büyük/küçük harfe duyarlı değildir, ancak belgeler ve SDK'lar tek bir yazım biçimi kullanmalıdır.

Sorgu parametreleri de JSON gövdesiyle aynı adlandırma stilini izlemelidir. Gövde alanlarınız snake_case ise:

?min_price=1000&created_after=2026-01-01
Enter fullscreen mode Exit fullscreen mode

Şunu kullanmayın:

?minPrice=1000
Enter fullscreen mode Exit fullscreen mode

Bir yanıtta created_at, sorguda ise createdAfter kullanmak istemci geliştiricilerini gereksiz hatalara zorlar.

Tüm kurallar bir bakışta

# Kural Yapın Yapmayın
1 Koleksiyonlarda çoğul isimler /products, /products/89 /getProducts, /productList
2 Yollarda fiil kullanmayın DELETE /orders/42 POST /deleteOrder/42
3 Kebab-case yol segmentleri /gift-cards /giftCards, /gift_cards
4 Tek bir JSON adlandırma stili Her yerde order_id orderId ve order_id karışık
5 En fazla iki iç içe geçme seviyesi /orders/1337/refunds /users/42/orders/1337/refunds/7
6 Filtre ve sayfalama sorgu parametrelerinde ?status=active&sort=-created_at /orders/active
7 Ana sürümü URL'de belirtin /v1/products /v1.2/products, sürüm başlıkları
8 Opak kaynak kimlikleri /orders/ord_9f8e2a71b3 /orders/42
9 Eylemler için denetleyici deseni POST /orders/42/cancel PATCH ile {"status":"cancelled"}
10 Tutarlı başlık ve parametre adları Idempotency-Key, ?min_price= X-IDEMPOTENCY_KEY, ?minPrice=

Kuralları ölçekli biçimde uygulayın

Bir wiki'deki stil rehberi tek başına yeterli değildir. Tutarlı API'ler geliştiren ekipler kuralları kod yazıldıktan sonra değil, tasarım aşamasında uygular. Bu, API yönetişiminin temelidir.

Apidog'un iş akışındaki değeri burada ortaya çıkar. Uç noktalar şema öncelikli görsel bir tasarımcıda tanımlanır. Böylece yol, adlandırma stili ve parametre isimleri kontrolör koduna gömülü dizeler olmaktan çıkar ve açık tasarım varlıklarına dönüşür.

Paylaşılan bileşenlerle Pagination, Error ve Money şemalarını bir kez tanımlayıp tüm uç noktalarda yeniden kullanabilirsiniz. Böylece yeni bir serviste per_page yerine pageSize gibi alternatifler icat edilmez.

Tasarımlar ekip çalışma alanında incelenir. Ekip liderleri /getUserOrders gibi hataları, üç istemci entegre olduktan sonra değil, yeniden adlandırmanın hâlâ tek tıklama kadar kolay olduğu tasarım aşamasında yakalar.

Onaylanan spesifikasyon; belgeleri, sahte sunucuları ve testleri yönlendirir. Böylece onayladığınız isimler, herkesin gönderdiği isimlerle aynı kalır.

Apidog'u indirin ve bir sonraki uç noktanızda ücretsiz deneyin. Eski bir API'yi sonradan düzeltmek zordur; yeni bir API'de doğru çizgiyi korumak ise çok daha kolaydır.

Sıkça Sorulan Sorular

REST URL'leri çoğul mu, tekil mi olmalı?

Birden fazla örneği olan tüm kaynaklar çoğul olmalıdır:

/products
/orders
/users
Enter fullscreen mode Exit fullscreen mode

Çoğul form hem koleksiyon (/orders) hem de tek bir üye (/orders/42) için doğal kalır. Gerçek tekiller için, örneğin `[REDACTED PATH]

Kaynak modellemesinin arkasındaki daha geniş yaklaşım için REST API nedir? kılavuzuna bakabilirsiniz.

JSON alan adlarında camelCase mi, snake_case mi kullanılmalı?

İkisinden biri diğerinden mutlak olarak daha iyi değildir.

  • camelCase, JavaScript ağırlıklı istemcilere uygundur.
  • snake_case, Python ve Ruby ile daha iyi eşleşir ve okunaklıdır.
  • Stripe genel API'sinde snake_case kullanır.

Birini seçin, stil rehberinize yazın ve şema incelemelerinde uygulayın. Uç noktalar arasında karma adlandırma, her iki seçimden de daha fazla sorun yaratır.

API sürümü URL'ye mi, başlığa mı eklenmeli?

Güçlü bir hipermedya gereksiniminiz yoksa sürümü URL'de belirtin:

http
/v1/orders

URL sürümleri günlüklerde, önbelleklerde ve tarayıcı testlerinde doğrudan görünür. Başlık sürümleme URL'leri sabit tutar; ancak istemci başlığı unutursa sessizce hatalı davranabilir.

Yalnızca ana sürümleri kullanın. Küçük değişiklikleri geriye dönük uyumlu ve bozucu olmayan güncellemeler olarak yayınlayın.

REST API yolunda fiil kullanılabilir mi?

Evet, yalnızca CRUD dışı eylemler için denetleyici uç noktalarında:

http
POST /orders/42/cancel
POST /payments/pay_88a1/retry

Fiil yolun sonunda, kendi kaynağının kapsamında yer almalıdır ve metot POST olmalıdır. Bunun dışındaki durumlarda fiili HTTP metodu taşır; URL ise yalnızca kaynak isimlerinden oluşur.

Kaynaklar

Top comments (0)