REST API Kaynak Adları Çoğul mu Tekil mi Olmalı?

TL;DR

REST API kaynak adları çoğul olmalıdır. /pet/{id} yerine /pets/{id} kullanın. Çoğul adlar, koleksiyonları tutarlı bir şekilde temsil eder, HTTP semantiğiyle uyumludur ve geliştiricilerin kaynaklar hakkında düşünme biçimleriyle eşleşir. Modern PetstoreAPI, endüstri en iyi uygulamalarını takip ederek API tasarımında baştan sona çoğul adlar kullanır.

Giriş

Bir REST API tasarlıyorsunuz. Kimliğe göre bir kullanıcı almak için bir uç noktaya ihtiyacınız var. /user/123 mi yoksa /users/123 mü kullanırsınız? Bu soru sayısız tartışmaya, Stack Overflow başlığına ve ekip içi anlaşmazlıklara yol açtı.

Cevap açık: çoğul kullanın. Ancak nedenini anlamak, kuralı ezberlemekten daha önemlidir. Mantık, REST'in nasıl çalıştığına, koleksiyonların nasıl davrandığına ve geliştiricilerin kaynaklar hakkında nasıl düşündüğüne bağlanır.

Eski Swagger Petstore bu konuda yanlış yapmış, /pets/{id} yerine /pet/{id} kullanmıştı. Bu tutarsızlık, milyonlarca geliştiriciye yanlış bir model öğretti. Modern PetstoreAPI, tüm uç noktalarda tutarlı bir şekilde çoğul adlar kullanarak bu durumu düzeltiyor.

💡

REST API'leri oluşturuyor veya test ediyorsanız, Apidog kaynak adlandırma kurallarını doğrulamanıza, uç nokta tutarlılığını test etmenize ve API'nizin REST en iyi uygulamalarını takip ettiğinden emin olmanıza yardımcı olur. OpenAPI belirtimlerini içe aktarabilir, adlandırma kalıplarını kontrol edebilir ve tutarsızlıkları üretime ulaşmadan önce yakalayabilirsiniz.

button

Bu kılavuzda, çoğul adların neden doğru seçim olduğunu, REST ilkeleriyle nasıl uyumlu olduklarını ve Modern PetstoreAPI'yi referans alarak bunları doğru bir şekilde nasıl uygulayacağınızı öğreneceksiniz.

Çoğul ve Tekil Tartışması

Tartışma, her iki yaklaşımın da ilk bakışta mantıklı görünmesinden kaynaklanmaktadır.

Tekil Argüman

“/user/123 isteği yaptığımda, birden fazla değil, tek bir kullanıcı alıyorum. Tekil mantıklı.”

Bu akıl yürütme, yanıta odaklanır—tek bir kaynak alıyorsunuz, bu yüzden URL tekil olmalı.

Çoğul Argüman

“URL bir koleksiyonu temsil eder. /users tüm kullanıcıların koleksiyonudur. /users/123 bu koleksiyondaki 123 numaralı öğedir.”

Bu akıl yürütme, kaynak yapısına odaklanır—URL'ler koleksiyonları temsil eder ve siz bu koleksiyonlardaki öğelere erişirsiniz.

Bu Neden Önemli?

Seçiminiz şunları etkiler:

API tutarlılığı - Karışık adlandırma geliştiricilerin kafasını karıştırır
Zihinsel modeller - Geliştiricilerin API yapınızı nasıl anladığı
Kod üretimi - Araçlar, kaynak adlarına göre istemci kodu üretir
Dokümantasyon açıklığı - Dokümanlar, adlandırma mantığınızı açıklamak zorundadır

Çoğul Adlar Neden Kazanır?

Çoğul kaynak adları, REST ilkeleri ve HTTP semantiğiyle uyumludur. İşte nedeni.

1. Koleksiyonlar Çoğuldur

REST'te kaynaklar koleksiyonlardır. /users adresine eriştiğinizde, kullanıcılar koleksiyonuna erişirsiniz. /users/123 adresine eriştiğinizde, kullanıcılar koleksiyonundaki 123 numaralı öğeye erişirsiniz.

GET /users          ← Kullanıcılar koleksiyonu
GET /users/123      ← Kullanıcılar koleksiyonundaki 123 numaralı öğe
POST /users         ← Kullanıcılar koleksiyonuna ekle
DELETE /users/123   ← Kullanıcılar koleksiyonundan 123 numaralı öğeyi kaldır

Bu zihinsel model tutarlıdır. Tüm öğelere veya tek bir öğeye erişiyor olsanız da, koleksiyon her zaman /users'tır.

Tekil adlarla zihinsel model bozulur:

GET /user           ← Hangi kullanıcı?
GET /user/123       ← Bu mantıklı
POST /user          ← Neye ekle?

2. HTTP Metotları Koleksiyonlar Üzerinde Çalışır

HTTP metotları koleksiyonlar üzerindeki işlemleri tanımlar:

GET /users - Koleksiyonu al
POST /users - Koleksiyona ekle
GET /users/123 - Koleksiyondan 123 numaralı öğeyi al
PUT /users/123 - Koleksiyondaki 123 numaralı öğeyi değiştir
DELETE /users/123 - Koleksiyondan 123 numaralı öğeyi kaldır

Koleksiyon kaynaktır. Bireysel öğeler o koleksiyonun üyeleridir.

3. Uç Noktalar Arası Tutarlılık

Çoğul adlar tutarlılık yaratır:

GET /pets           ← Koleksiyon
GET /pets/123       ← Koleksiyondaki öğe
GET /orders         ← Koleksiyon
GET /orders/456     ← Koleksiyondaki öğe

Tekil adlar sizi tekil ve çoğul arasında geçiş yapmaya zorlar:

GET /pet            ← Mantıklı değil
GET /pet/123        ← Mantıklı
GET /pets           ← Dur, şimdi çoğul mu oldu?

4. Endüstri Standartları

Büyük API'ler çoğul adlar kullanır:

GitHub API: /repos, /users, /issues
Stripe API: /customers, /charges, /subscriptions
Twilio API: /accounts, /messages, /calls
Google API'leri: /users, /groups, /files

Modern PetstoreAPI, /pets, /orders, /users ile bu standardı takip eder.

Koleksiyon Zihinsel Modeli

Koleksiyonları anlamak, daha iyi API'ler tasarlamanıza yardımcı olur.

REST'teki Koleksiyonlar

Koleksiyon, bir kaynak kümesidir. Bir evcil hayvan mağazası API'sinde:

/pets - Tüm evcil hayvanların koleksiyonu
/orders - Tüm siparişlerin koleksiyonu
/users - Tüm kullanıcıların koleksiyonu

Her koleksiyon işlemleri destekler:

GET /pets           ← Evcil hayvanları listele (filtreleme, sayfalama ile)
POST /pets          ← Yeni bir evcil hayvan oluştur
GET /pets/{id}      ← Belirli bir evcil hayvanı al
PUT /pets/{id}      ← Belirli bir evcil hayvanı güncelle
DELETE /pets/{id}   ← Belirli bir evcil hayvanı sil

Alt Koleksiyonlar

Koleksiyonlar alt koleksiyonlar içerebilir:

GET /pets/{id}/photos           ← {id} evcil hayvanı için fotoğraf koleksiyonu
POST /pets/{id}/photos          ← {id} evcil hayvanına fotoğraf ekle
GET /pets/{id}/photos/{photoId} ← Belirli fotoğraf

Desen tutarlı kalır: koleksiyonlar çoğuldur, öğelere Kimlik ile erişilir.

Modern PetstoreAPI Örneği

Modern PetstoreAPI bunu doğru bir şekilde uygular:

GET /pets
GET /pets/{petId}
GET /pets/{petId}/photos
POST /pets/{petId}/vaccinations
GET /orders
GET /orders/{orderId}
GET /orders/{orderId}/items

Her koleksiyon çoğuldur. Her öğe erişimi, o koleksiyon içinde {id} kullanır.

Modern PetstoreAPI Çoğul Adları Nasıl Kullanır?

Modern PetstoreAPI'den gerçek örneklere bakalım.

Evcil Hayvan Kaynakları

GET    /pets                    ← Tüm evcil hayvanları listele
POST   /pets                    ← Yeni bir evcil hayvan oluştur
GET    /pets/{petId}            ← Belirli evcil hayvanı al
PUT    /pets/{petId}            ← Evcil hayvanı güncelle
DELETE /pets/{petId}            ← Evcil hayvanı sil
GET    /pets?status=AVAILABLE   ← Evcil hayvanları duruma göre filtrele

Sipariş Kaynakları

GET    /orders                  ← Tüm siparişleri listele
POST   /orders                  ← Sipariş oluştur
GET    /orders/{orderId}        ← Belirli siparişi al
PUT    /orders/{orderId}        ← Siparişi güncelle
DELETE /orders/{orderId}        ← Siparişi iptal et

Kullanıcı Kaynakları

GET    /users                   ← Kullanıcıları listele
POST   /users                   ← Kullanıcı oluştur
GET    /users/{userId}          ← Belirli kullanıcıyı al
PUT    /users/{userId}          ← Kullanıcıyı güncelle
DELETE /users/{userId}          ← Kullanıcıyı sil

İç İçe Kaynaklar

GET /pets/{petId}/photos                    ← Evcil hayvanın fotoğrafları
POST /pets/{petId}/photos                   ← Fotoğraf ekle
GET /pets/{petId}/vaccinations              ← Evcil hayvanın aşıları
POST /pets/{petId}/vaccinations             ← Aşıyı kaydet
GET /orders/{orderId}/items                 ← Sipariş öğeleri

Tüm uç nokta listeleri için tam REST API dokümantasyonunu kontrol edin.

Tekil İçin Yaygın Argümanlar (ve Neden Yanlış Oldukları)

Tekil adlar için yaygın argümanları ele alalım.

Argüman 1: “Yanıt Tekildir”

İddia: “/user/123 ile GET isteği yaptığımda, tek bir kullanıcı alırım. Tekil mantıklı.”

Karşı Argüman: URL, kaynağın konumunu temsil eder, yanıtı değil. /users/123, “kullanıcılar koleksiyonundaki 123 numaralı öğe” anlamına gelir. Yanıtın tekil olması, koleksiyon yapısını değiştirmez.

Argüman 2: “Kotta Daha İyi Okunur”

İddia: “getUser(id) kodu getUsers(id)'den daha iyi okunur.”

Karşı Argüman: İstemci kodunuzun adlandırması URL yapısından bağımsızdır. Şunlara sahip olabilirsiniz:

// URL: GET /users/123
function getUser(id) {
  return api.get(`/users/${id}`);
}

Fonksiyon adının URL ile eşleşmesi gerekmez.

Argüman 3: “Tekil Dilbilgisi Sorunlarını Önler”

İddia: “'status' veya 'information' gibi açık çoğulları olmayan kaynaklar ne olacak?”

Karşı Argüman: Bunlar genellikle koleksiyonlar değil, tekil kaynaklardır. Tekil olanlar için tekil kullanın:

GET /status         ← Sistem durumu (tekil)
GET /configuration  ← Uygulama yapılandırması (tekil)
GET /users          ← Kullanıcılar koleksiyonu (çoğul)

Argüman 4: “ORM'im Tekil Tablo Adları Kullanıyor”

İddia: “Veritabanı tablolarım tekildir (user, order), bu yüzden API'm de eşleşmeli.”

Karşı Argüman: API tasarımınız veritabanı uygulama detaylarını sızdırmamalıdır. REST API'leri veritabanı tablolarını değil, kaynakları temsil eder. Veritabanı şemanızdan bağımsız olarak koleksiyonlar için çoğul kullanın.

Apidog ile Kaynak Adlandırmasını Test Etme

Apidog, kaynak adlandırma kurallarını doğrulamanıza ve test etmenize yardımcı olur.

Modern PetstoreAPI'yi İçe Aktarma

Modern PetstoreAPI OpenAPI spesifikasyonunu içe aktarın
Apidog kaynak kalıplarını otomatik olarak algılar
Tutarlılık için uç nokta adlandırmasını inceleyin

Adlandırma Kuralı Testleri Oluşturma

// Apidog test betiği
pm.test("Kaynak adları çoğuldur", function() {
  const path = pm.request.url.getPath();
  const segments = path.split('/').filter(s => s);

  // İlk segmentin çoğul olduğunu kontrol et
  const resource = segments[0];
  pm.expect(resource).to.match(/s$/); // 's' ile biter
});

Tutarlılığı Doğrulama

Apidog şunları kontrol edebilir:

Tüm koleksiyon uç noktalarının çoğul adlar kullandığını
Alt kaynakların aynı deseni takip ettiğini
Aynı API'de tekil/çoğul adlandırmanın karıştırılmadığını

Gerçek İsteklerle Test Etme

GET https://api.petstoreapi.com/v1/pets
GET https://api.petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24
GET https://api.petstoreapi.com/v1/orders

Apidog yanıtları doğrular ve API'niz genelinde adlandırma tutarlılığını sağlamanıza yardımcı olur.

Kenar Durumlar ve İstisnalar

Bazı kaynaklar çoğul kalıbına uymaz.

Tekil Kaynaklar

Yalnızca bir kez var olan kaynaklar tekil olmalıdır:

GET /status         ← Sistem durumu
GET /configuration  ← Uygulama yapılandırması
GET /health         ← Sağlık kontrolü
GET /metrics        ← Sistem metrikleri

Bunlar koleksiyon değildir, bu yüzden çoğul uygulanmaz.

Kontrolör Kaynakları

CRUD işlemlerine uymayan eylemler:

POST /login         ← Kimlik doğrulama eylemi
POST /logout        ← Oturum sonlandırma
POST /search        ← Karmaşık arama işlemi

Bunlar, kaynakları değil eylemleri temsil ettikleri için kabul edilebilir istisnalardır.

Sayılamayan İsimler

Bazı isimlerin açık çoğulları yoktur:

GET /information    ← Tekil (sayılamayan)
GET /data           ← Tekil (sayılamayan)
GET /equipment      ← Tekil (sayılamayan)

Sayılamayan isimler için tekil kullanın, ancak bunlar tipik API'lerde nadirdir.

Modern PetstoreAPI Yaklaşımı

Modern PetstoreAPI bu durumları şöyle ele alır:

# Koleksiyonlar (çoğul)
GET /pets
GET /orders
GET /users

# Tekil Kaynaklar (tekil)
GET /health
GET /metrics

# Eylemler (tekil fiiller)
POST /login
POST /logout

Sonuç

REST API kaynak adları çoğul olmalıdır. Bu, koleksiyon semantiği, HTTP metotları ve endüstri standartlarıyla uyumludur. Modern PetstoreAPI, bu deseni tüm uç noktalarda doğru bir şekilde gösterir.

Önemli çıkarımlar:

Koleksiyonlar için çoğul adlar kullanın (/pets, /orders, /users)
Bireysel öğelere koleksiyonlar içinde erişilir (/pets/123)
Tekil kaynaklar tekil olabilir (/status, /health)
Tutarlılık, mükemmellikten daha önemlidir
Adlandırma kurallarınızı Apidog ile test edin

Çoğul ve tekil tartışması çözüme kavuştu. Endüstri standardını takip edin, çoğul adlar kullanın ve geliştiricilerin sezgisel olarak anlayabileceği API'ler oluşturun.

Sonraki adımlar:

Adlandırma tutarlılığı için API uç noktalarınızı gözden geçirin
Referans kalıpları için Modern PetstoreAPI dokümantasyonunu kontrol edin
API tasarımınızı doğrulamak için Apidog'u kullanın
OpenAPI spesifikasyonunuzu çoğul kaynak adlarıyla güncelleyin

Sıkça Sorulan Sorular

Mevcut API'mi tekilden çoğula değiştirmeli miyim?

API'niz zaten üretimdeyse, kaynak adlarını değiştirmek önemli bir değişikliktir. Şunları göz önünde bulundurun:

Çoğul adlara sahip yeni v2 uç noktaları eklemek
Yönlendirmelerle geriye dönük uyumluluğu sürdürmek
Adlandırma kuralını açıkça belgelemek

Sadece adlandırma tutarlılığı için mevcut istemcileri bozmayın.

Zaten çoğul olan kaynaklar ne olacak?

Kaynak adı doğal olarak çoğulsa (örneğin “analytics” veya “series” gibi), olduğu gibi bırakın:

GET /analytics      ← Zaten çoğul
GET /series         ← Zaten çoğul
GET /species        ← Zaten çoğul

İç içe kaynakları nasıl ele alırım?

Her iki seviyeyi de çoğul tutun:

GET /users/{userId}/orders              ← Her ikisi de çoğul
GET /pets/{petId}/vaccinations          ← Her ikisi de çoğul
GET /orders/{orderId}/items             ← Her ikisi de çoğul

Ekibim tekili tercih ederse ne olur?

API'nizdeki tutarlılık en önemlidir. Ekibiniz zaten tekil adları standartlaştırdıysa ve değiştirmek kafa karışıklığına neden olacaksa, tekilde kalın. Ancak yeni API'ler için çoğul kullanın.

GraphQL çoğul mu yoksa tekil mi kullanır?

GraphQL genellikle tek öğeli sorgular için tekil, listeler için çoğul kullanır:

query {
  user(id: "123") { ... }      # Tekil
  users(limit: 10) { ... }     # Çoğul
}

Bu, REST'ten farklıdır çünkü GraphQL sorguları, bir mi yoksa çok mu döndürüleceği konusunda açıktır.

Modern PetstoreAPI bunu nasıl ele alır?

Modern PetstoreAPI, tüm REST uç noktalarında çoğul adları tutarlı bir şekilde kullanır. Tam örnekler için REST API kılavuzunu kontrol edin.

Adlandırma kurallarını otomatik olarak test edebilir miyim?

Evet, Apidog, tüm API'nizdeki kaynak adlandırma kalıplarını kontrol etmek için otomatik testler çalıştırabilir. OpenAPI spesifikasyonunuzu içe aktarın ve adlandırma kuralları için test senaryoları oluşturun.

İngilizce olmayan API'ler ne olacak?

Çoğul kuralı dilden bağımsız olarak geçerlidir. API'niz Fransızca kaynak adları kullanıyorsa, Fransızca çoğulları kullanın. Japonca kullanıyorsa, Japonca dilbilgisi kurallarına uyun. İlke (koleksiyonlar çoğuldur) aynı kalır.