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, /Users/fetchAll, üç farklı sayfalama şeması ve aynı yanıtta order_id yanında duran bir customerID alanı. Bunların hiçbiri hiçbir şeyi bozmaz. Hepsi herkesi yavaşlatır.

İsimlendirme, yapacağınız en ucuz API tasarım kararı ve geri döndürmesi en pahalı olanıdır. Müşteriler /getOrders'a bağımlı hale geldiğinde, yıllarca onu desteklemek zorunda kalırsınız. Bu kılavuz, bir REST API'nin size dayattığı her adlandırma kararı için somut bir kural sunar; her biri için bir örnek ve bir anti-örnek içerir. Daha geniş geliştiriciler için REST API yönergelerimizle aynı düşünceyi takip eder, ancak ekiplerin en çok tartıştığı kısma odaklanır: şeylere ne isim verileceği.

Bu kuralları kod inceleme yorumlarından ziyade araçlarla uygulamayı tercih ediyorsanız, Apidog, herkes kod yazmadan önce her uç noktayı paylaşılan bir şemaya göre görsel olarak tanımlamanıza olanak tanır. Bununla ilgili daha fazla bilgiyi sonda bulabilirsiniz.

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

Bir URL bir işlemi değil, bir kaynağı adlandırır. Koleksiyonlar nesne kümeleridir, bu yüzden onları çoğul isimlerle adlandırın.

Yapın:

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

Yapmayın:

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

Çoğul form her iki seviyede de işe yarar. /products "ürün koleksiyonu" olarak okunurken, /products/89 "koleksiyondaki 89 numaralı ürün" olarak okunur. Tekil adlandırma, tek bir öğe için /product/89 gibi garip URL'leri zorlar, ancak çoğu için /product, bu da yanlış okunur. Microsoft REST API yönergeleri tam olarak bu nedenle çoğul isimler üzerinde karar kıldı ve çoğu genel API (Stripe, GitHub, Shopify) aynı yolu izledi.

Bir istisna: tekil kaynaklar. Bir kullanıcının tam olarak bir sepeti varsa, /users/42/cart uygundur. Tekillik içeren bir şeyi çoğul yapmayın.

Yollardan fiilleri çıkarın

HTTP metodu fiildir. Yola başka bir fiil eklemek bilgiyi tekrar eder ve kaynak modelini bozar.

Yapın:

GET    /v1/orders/42      (onu oku)
DELETE /v1/orders/42      (onu sil)
PATCH  /v1/orders/42      (onu güncelle)

Yapmayın:

GET  /v1/fetchOrder/42
POST /v1/deleteOrder/42
POST /v1/updateOrderStatus

Fiil tabanlı yollar aynı zamanda yüzey alanınızı da artırır. Dört metodu olan bir kaynak, ayrı ayrı belgelenecek, test edilecek ve önbelleğe alınacak dört uç nokta haline gelir. Önbellek geçersiz kılma da kötüleşir: bir CDN, GET /v1/orders/42'yi önbelleğe alabilir ve DELETE /v1/orders/42 üzerinde geçersiz kılabilir, çünkü her ikisi de aynı URL'yi işaret eder. /fetchOrder/42 ile /deleteOrder/42 arasında bağlantı kuramaz.

URL yollarında kebab-case kullanın

Çok kelimeli yol segmentleri bir ayırıcıya ihtiyaç duyar ve tireler doğru olanıdır.

Yapın:

/v1/gift-cards
/v1/shipping-addresses

Yapmayın:

/v1/giftCards
/v1/gift_cards
/v1/GiftCards

Üç neden var. Google, tireleri indeksleme için kelime ayırıcı olarak kabul eder, bu nedenle genel API belgeleri kebab-case ile daha iyi sıralanır. Bir URL bir e-postada veya belgede altı çizildiğinde alt çizgiler kaybolur. Ve URL'lerde camelCase, büyük/küçük harf duyarlılığı hatalarına yol açar: /giftCards ve /giftcards çoğu sunucuda farklı URL'lerdir ve birisi yanlış olanı yazacaktır. Zalando RESTful API yönergeleri kebab-case'i ZORUNLU bir kural haline getirir ve bu stratejiyi yüzlerce dahili serviste uygulamışlardır.

Tek bir JSON harf büyüklüğü seçin ve bunu yazılı hale getirin

İstek ve yanıt gövdelerindeki alan adları için dürüst cevap: camelCase ve snake_case her ikisi de çalışır. Çalışmayan şey ise bunları karıştırmaktır.

Yapın (birini tutarlı bir şekilde):

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

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

Yapmayın:

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

camelCase, JavaScript ve Java istemcilerine net bir şekilde eşleşir. snake_case, taranması daha kolaydır ve Ruby, Python ve çoğu SQL sütun adıyla uyumludur; Stripe bunu her yerde kullanır. API'nizi en çok kimin kullandığına göre bir seçim yapın, ardından bu seçimi stil rehberinize ekleyin, böylece tartışma her çekme isteğinde değil, bir kez yaşansın. Karma durumlandırma, gerçek dünyadaki API'lerdeki en yaygın tutarsızlıktır çünkü farklı ekipler farklı uç noktalar gönderir. Bu bir yönetim hatasıdır, zevk hatası değil.

İç içe geçmeyi iki seviyeyle sınırlayın

İç içe geçirme sahiplenmeyi ifade eder: /users/42/orders "42 numaralı kullanıcıya ait siparişler" anlamına gelir. Bu yararlıdır. İki seviyeden sonra yararlılığını kaybeder.

Yapın:

GET /v1/users/42/orders
GET /v1/orders/1337/refunds

Yapmayın:

GET /v1/users/42/orders/1337/refunds/7/status

Derin iç içe geçirme, istemcileri bir yaprak kaynağa ulaşmak için her ata kimliğini taşımaya zorlar, hatta yaprağın kendine ait küresel benzersiz bir kimliği olsa bile. Eğer bir geri ödemenin kimliği 7 ise, bunu /refunds/7 veya /orders/1337/refunds/7 adresinde gösterin ve orada durun. İyi bir koku testi: eğer bir URL üç veya daha fazla kimlik içeriyorsa, onu düzleştirin. Bir sipariş oluştuktan sonra, yolunda kullanıcısına ihtiyaç duymaz; /orders/1337 tek başına yeterlidir.

Filtrelemeyi, sıralamayı ve sayfalama işlemlerini sorgu parametrelerine koyun

Yollar kaynakları tanımlar. Sorgu parametreleri, bunları nasıl görüntülediğinizi değiştirir. Bir filtreyi asla yola kodlamayın.

Yapın:

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

Yapmayın:

GET /v1/orders/active
GET /v1/orders/sorted-by-date-desc
GET /v1/getOrdersByStatusAndDate

sort=-created_at deseni (azalan için eksi ön eki) JSON:API belirtiminden gelir ve size ikinci bir order=desc parametresinden tasarruf sağlar. /orders/active gibi filtre yolları zararsız görünür, ancak filtreleri birleştirmeniz gerekene kadar, o zaman her kombinasyon için yeni bir uç nokta oluşturursunuz. Sayfalama parametre adları da aynı disiplini hak eder: limit/cursor veya page/per_page'i bir kez seçin ve her koleksiyonda yeniden kullanın. API sayfalama kılavuzumuz, imleç ve ofset karşılaştırmasını derinlemesine ele alır; buradaki adlandırma kuralı sadece bu konuda tekdüze olmaktır.

Sürümü yolda belirtin

İki ana akım seçeneğiniz var: bir yol segmenti (/v1/products) veya bir başlık (Accept: application/vnd.myapi.v1+json). Başlık sürümleme daha "saf" bir REST yaklaşımıdır, çünkü URL sürümler arasında aynı kaynağı adlandırmaya devam eder ve Google API tasarım rehberliği her iki yaklaşımın da yaygın olduğunu belirtir. Ancak yol sürümleme, operasyonel nedenlerle öne çıkar: her günlük satırında görünür, bir tarayıcıdan test edilebilir, Vary jimnastiği olmadan önbelleğe alınabilir ve bir istemcinin unutması imkansızdır. Eksik bir sürüm başlığından kaynaklanan "curl'de çalışıyor, üretimde hata veriyor" sorununu gidermiş her geliştirici, alternatifin maliyetini bilir. Yalnızca ana sürümle /v1/ kullanın, /v1.2/ değil; küçük değişiklikler eklemeli ve bozucu olmayan olmalıdır. İçerik anlaşması da dahil olmak üzere tüm karar ağacı için API sürümleme stratejileri karşılaştırmamıza bakın.

Kaynak kimliklerini opak olarak ele alın ve sıralı tam sayıları dikkatsizce sızdırmayın

/orders/41, /orders/42, /orders/43: sıralı tam sayı kimlikleri, bakan herkese tam olarak kaç sipariş işlediğinizi söyler ve bir saldırganın kimlik alanını yetkilendirme boşluklarını araştırarak gezdiği numaralandırma saldırılarına davetiye çıkarır. Bu tür bir hata, bozuk nesne seviyesi yetkilendirme, OWASP API Güvenliği Top 10 listesinde bir numarada yer almaktadır.

Yapın:

GET /v1/orders/ord_9f8e2a71b3
GET /v1/users/550e8400-e29b-41d4-a716-446655440000

Yapmayın (numaralandırma önemli olduğunda):

GET /v1/orders/42
GET /v1/invoices/10883

Stripe'ın ord_9f8e2a71b3 gibi ön ekli rastgele kimlikler en güçlü desendir: tahmin edilemez, günlüklerde kendini açıklayıcı ve ifşa edilmesi güvenlidir. Yetkilendirme kontrolleri her iki durumda da zorunludur. Opak kimlikler, eksik bir kontrolün etki alanını azaltır; yerini almazlar. Dahili olarak tam sayı birincil anahtarlar kullanmaya devam edebilirsiniz; kural, URL'lerde neyi ifşa ettiğinizle ilgilidir.

CRUD dışı eylemleri kontrolör kaynakları olarak modelleyin

Er ya da geç, temiz bir CRUD eşleşmesi olmayan bir eyleme ihtiyacınız olacak: bir siparişi iptal etme, bir ödemeyi yeniden deneme, bir e-postayı yeniden gönderme. Bunu bir durum alanında PATCH aracılığıyla tünellemeyin ve en üst seviyeye bir fiil koymayın.

Yapın:

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

Yapmayın:

PATCH /v1/orders/42        { "status": "cancelled" }
POST  /v1/cancelOrder      { "orderId": 42 }

Bu, denetleyici desenidir ve fiil yok kuralının onaylanmış tek istisnasıdır: fiil, üzerinde işlem yapılan kaynağın altında, yolun sonunda yer alır. PATCH yaklaşımı RESTful görünür, ancak bir alan güncellemesinin içinde bir durum makinesi gizler. Bir siparişi iptal etmek, para iadelerini tetikler, envanteri serbest bırakır ve bildirimler gönderir; bunun bir alan yazımı gibi davranmak, sunucunuzu amacı algılamak için yükleri farklılaştırmaya zorlar. Bir /cancel uç noktası amacı belirtir, eyleme kendi izinlerini ve denetim izini verir ve bir iptal nedeni gibi eyleme özgü girdiler için yer bırakır.

Başlıklar ve sorgu parametreleri için harf büyüklüğünü tutarlı tutun

İki küçük yüzey, aynı disiplin. Özel başlıklar, HTTP kuralına uygun olarak Hyphenated-Pascal-Case kullanır: Idempotency-Key, Request-Id. Eski X- ön ekini atlayın; 2012'de RFC 6648 tarafından kullanım dışı bırakıldı. Başlık adları ağ üzerinde büyük/küçük harf duyarlı değildir, ancak belgeleriniz ve SDK'larınız bunları yine de tek bir şekilde yazmalıdır.

Sorgu parametreleri JSON gövde harf büyüklüğünüzle eşleşmelidir. Gövdeleriniz snake_case kullanıyorsa, ?minPrice=1000 yerine ?min_price=1000&created_after=2026-01-01 yazın. Bir yanıtta created_at okuyup bir sorguda createdAfter yazmak zorunda kalan bir geliştirici, ilk denemede yanlış yapacaktır ve ondan sonraki herkes de öyle.

Tüm kural seti bir bakışta

Kuralları ölçekte uygulamak

Bir wiki'deki stil rehberi hiçbir şeyi değiştirmez. API'leri tutarlı kalan ekiplerin tek bir alışkanlığı vardır: önce tasarlar ve kod var olmadan önce kuralları uygularlar; bu, pratikte API yönetişiminin temelidir.

Apidog'un iş akışındaki yerini kazandığı yer burasıdır. Uç noktalar, şema öncelikli bir görsel tasarımcıda tanımlanır, böylece yol, harf büyüklüğü ve parametre adları, kontrolör kodunda gömülü dizeler yerine açık tasarım eserleridir. Paylaşılan bileşenler, Pagination, Error ve Money şemalarının bir kez tanımlanıp her uç noktada yeniden kullanılması anlamına gelir; kimse yeni bir serviste per_page'i pageSize olarak yeniden icat etmez. Ve tasarımlar, inceleme özelliği entegre edilmiş ekip çalışma alanlarında yaşadığı için, bir lider, üç istemci entegre ettikten sonra değil, yeniden adlandırmanın tek bir tıklamaya mal olduğu tasarım aşamasında /getUserOrders gibi hataları yakalayabilir. Spesifikasyon daha sonra belgeleri, sahte sunucuları ve testleri yönlendirir, böylece onayladığınız adlar herkesin gönderdiği adlar olur. Apidog'u indirin ve bir sonraki yeni uç noktanızla ücretsiz deneyin; eski bir API'yi uyarlamak zordur, ancak yenilerde çizgiyi korumak değildir.

Sıkça Sorulan Sorular

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

Birden fazla örneği olan tüm kaynaklar için çoğul olmalı: /products, /orders, /users. Ç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 /users/42/cart) tekil adlar ayırın. Kaynak modellemesinin arkasındaki daha derin mantığı merak ediyorsanız, REST API nedir başlıklı kılavuzumuz, bunu temel prensiplerden başlayarak ele almaktadır.

JSON alan adları için camelCase mi yoksa snake_case mi daha iyidir?

Hiçbiri liyakat açısından kazanmaz. camelCase, JavaScript ağırlıklı tüketicilere uyar; snake_case daha okunaklıdır ve Python, Ruby ve Stripe'ın genel API'siyle eşleşir. Keskin kural: birini seçin, stil rehberinize yazın ve şema incelemesinde uygulayın. Uç noktalar arasında karma harf büyüklüğü, her iki seçimden de daha fazla zarar verir.

API sürümünü URL'ye mi yoksa bir başlığa mı koymalıyım?

Güçlü bir hipermedya gereksiniminiz yoksa yolu kullanın (/v1/orders). Yol sürümleri, günlüklerde, önbelleklerde ve tarayıcı testlerinde sıfır istemci çabasıyla görünür. Başlık sürümleme, URL'leri sürümler arasında sabit tutar ancak istemciler başlığı unuttuğunda sessizce başarısız olur. Yalnızca ana sürümler; küçük değişiklikleri eklemeli, bozucu olmayan güncellemeler olarak gönderin.

REST API yolunda fiiller kabul edilebilir mi?

Evet, tek bir yerde: CRUD dışı eylemler için kontrolör uç noktalarında, örneğin POST /orders/42/cancel veya POST /payments/pay_88a1/retry gibi. Fiil, yolun sonunda, kendi kaynağının kapsamında yer alır ve metot her zaman POST'tur. Diğer her yerde, HTTP metodu fiili taşır ve yol sadece isimlerden oluşur.