REST API URL'lerinde Neden Fiil Kullanmamalısınız?

ÖZET

REST API URL'leri eylemler (fiiller) yerine isimler (kaynaklar) içermelidir. HTTP metotları (GET, POST, PUT, DELETE) fiillerdir. `/getUser` veya `/createOrder` gibi eylem fiilleri kullanmak REST prensiplerini ihlal eder, tutarsızlık yaratır ve API'lerin bakımını zorlaştırır. Modern PetstoreAPI, baştan sona kaynak odaklı URL'ler kullanmaktadır.

Giriş

Evcil hayvanları duruma göre aramak için bir API uç noktası tasarlıyorsunuz. İlk içgüdünüz şu olabilir: GET /findPetsByStatus?status=available. Açıklayıcı, net ve tam olarak ne yaptığını anlatıyor. Ancak bu hatalı bir tasarımdır.

REST API'ler URL'lerde fiil yerine isim kullanmalıdır. HTTP metodu fiildir. GET /pets?status=available doğru tasarımdır. URL kaynağı (evcil hayvanlar) temsil eder ve metot eylemi (al) temsil eder.

Eski Swagger Petstore, /pet/findByStatus ve /pet/findByTags gibi uç noktalarla bu hatayı yapmıştır. URL'lerdeki bu eylem fiilleri REST prensiplerini ihlal eder ve bakım sorunları yaratır. Modern PetstoreAPI, tutarlı bir şekilde kaynak odaklı URL'ler kullanarak bunu düzeltir.

Bu rehberde, fiillerin neden REST URL'lerine ait olmadığını, kaynak odaklı uç noktaların nasıl tasarlanacağını ve Modern PetstoreAPI'nin bunu nasıl doğru bir şekilde uyguladığını öğreneceksiniz.

REST API'lerinde Fiil Sorunu

URL'lerdeki eylem fiilleri, REST terimleriyle değil, RPC (Remote Procedure Call) terimleriyle düşündüğünüzü gösterir.

RPC Tarzı URL'ler (Yanlış)

POST /createUser
GET /getUser?id=123
PUT /updateUser
DELETE /deleteUser?id=123
GET /findUsersByRole?role=admin
POST /sendEmail
GET /calculateTotal

Bu URL'ler eylemleri tanımlar. Fonksiyon çağrıları gibi okunurlar: createUser(), getUser(), sendEmail().

REST Tarzı URL'ler (Doğru)

POST /users
GET /users/123
PUT /users/123
DELETE /users/123
GET /users?role=admin
POST /emails
GET /orders/123/total

Bu URL'ler kaynakları tanımlar. HTTP metodu eylemi sağlar.

Bu Neden Önemli?

Tutarlılık: REST URL'leri öngörülebilir bir düzeni takip eder. Kaynak adını öğrendikten sonra tüm uç noktaları bilirsiniz:

• GET /pets - Evcil hayvanları listele
• POST /pets - Evcil hayvan oluştur
• GET /pets/{id} - Evcil hayvan al
• PUT /pets/{id} - Evcil hayvanı güncelle
• DELETE /pets/{id} - Evcil hayvanı sil

Fiil tabanlı URL'lerle her uç nokta benzersizdir. Takip edilecek bir düzen yoktur.

Ölçeklenebilirlik: API'niz büyüdükçe, fiil tabanlı URL'ler çoğalır:

• /findPetsByStatus
• /findPetsByTags
• /findPetsByOwner
• /findPetsByBreed
• /searchPets
• /queryPets

Kaynak odaklı URL'ler sorgu parametreleri kullanır:

• GET /pets?status=available
• GET /pets?tags=friendly
• GET /pets?owner=john
• GET /pets?breed=labrador

Tek bir uç nokta tüm filtrelemeleri halleder.

HTTP Metotları Neden Fiillerdir?

REST, HTTP'nin yerleşik fiillerini kullanır. Kendi fiillerinizi icat etmenize gerek yoktur.

HTTP Metotları CRUD İşlemlerine Eşleşir

POST   → Oluştur
GET    → Oku
PUT    → Güncelle (değiştir)
PATCH  → Güncelle (kısmi)
DELETE → Sil

Bu metotların tanımlanmış anlamları vardır. GET güvenli ve idempotenttir. POST kaynaklar oluşturur. DELETE onları kaldırır.

Örnek: Kullanıcı Yönetimi

Yanlış (URL'lerdeki fiiller):

POST /createUser
GET /getUser?id=123
POST /updateUser
POST /deleteUser

Her işlem farklı bir URL kullanır. HTTP metodu anlam ifade etmez.

Doğru (HTTP metotları fiil olarak):

POST /users           ← Kullanıcı oluştur
GET /users/123        ← Kullanıcı al
PUT /users/123        ← Kullanıcıyı güncelle
DELETE /users/123     ← Kullanıcıyı sil

URL aynı kalır. Metot değişir.

HTTP Metotları Kullanmanın Faydaları

1. Önbellekleme: GET istekleri önbelleğe alınabilir. Tarayıcılar ve proxy'ler bunu bilir. Eğer POST /getUser kullanırsanız, önbellekleme bozulur.

2. Idempotency: PUT ve DELETE idempotenttir. Bunları birden çok kez çağırmak, bir kez çağırmakla aynı etkiye sahiptir. Bu, yeniden deneme mantığı için önemlidir.

3. Güvenlik: GET güvenlidir; durumu değiştirmez. Araçlar ve tarayıcılar GET uç noktalarını güvenle çağırabilir.

4. Standartlara Uyum: HTTP istemcileri, proxy'ler ve önbellekler HTTP metotlarını anlar. Özel fiillerinizi anlamazlar.

Swagger Petstore'dan Gerçek Örnekler

Eski Swagger Petstore, fiil tabanlı birkaç uç nokta içerir.

Örnek 1: Duruma Göre Evcil Hayvan Bulma

Swagger Petstore (Yanlış):

GET /pet/findByStatus?status=available

Sorunlar:

• findByStatus bir fiil öbeğidir
• /pet/{id} uç noktasıyla tutarsız
• Kolayca genişletilemez (diğer kriterlere göre bulma ne olacak?)

Modern PetstoreAPI (Doğru):

GET /pets?status=AVAILABLE

Faydaları:

• Kaynak odaklı (/pets)
• Filtreleme için sorgu parametreleri kullanır
• Diğer uç noktalarla tutarlı
• Kolayca genişletilebilir: GET /pets?status=AVAILABLE&species=dog

Tam uygulama için Modern PetstoreAPI REST dokümantasyonuna bakınız.

Örnek 2: Etiketlere Göre Evcil Hayvan Bulma

Swagger Petstore (Yanlış):

GET /pet/findByTags?tags=tag1,tag2

Modern PetstoreAPI (Doğru):

GET /pets?tags=friendly,trained

Örnek 3: Kullanıcı Girişi

Swagger Petstore (Yanlış):

GET /user/login?username=john&password=secret

Birden çok sorun:

• login bir fiildir
• Kimlik doğrulama için GET kullanma (güvenlik felaketi)
• URL sorgu parametrelerinde şifreler

Modern PetstoreAPI (Doğru):

POST /auth/login
Content-Type: application/json

{
  "username": "john",
  "password": "secret123"
}

Faydaları:

• Kaynak odaklı (/auth)
• Doğru HTTP metodu (POST)
• Kimlik bilgileri URL'de değil, istek gövdesinde
• Sonraki istekler için JWT belirteci döndürür

Modern PetstoreAPI Bunu Nasıl Düzeltir?

Modern PetstoreAPI, baştan sona kaynak odaklı URL'ler kullanır.

Evcil Hayvan Yönetimi

GET /pets                    ← Tüm evcil hayvanları listele
GET /pets?status=AVAILABLE   ← Duruma göre filtrele
GET /pets?species=dog        ← Türlere göre filtrele
GET /pets/{id}               ← Belirli bir evcil hayvanı al
POST /pets                   ← Yeni evcil hayvan oluştur
PUT /pets/{id}               ← Evcil hayvanı güncelle
PATCH /pets/{id}             ← Kısmi güncelleme
DELETE /pets/{id}            ← Evcil hayvanı sil

Fiil yok. Sadece kaynaklar ve HTTP metotları.

Sipariş Yönetimi

GET /orders                  ← Siparişleri listele
GET /orders/{id}             ← Sipariş al
POST /orders                 ← Sipariş oluştur
PUT /orders/{id}             ← Siparişi güncelle
DELETE /orders/{id}          ← Siparişi iptal et
GET /orders/{id}/items       ← Sipariş öğelerini al

Karmaşık İşlemler

CRUD modeline temiz bir şekilde uymayan işlemler için Modern PetstoreAPI alt kaynaklar kullanır:

POST /orders/{id}/payment    ← Sipariş için ödeme işle
POST /orders/{id}/shipment   ← Sipariş için gönderi oluştur
POST /pets/{id}/adoption     ← Evcil hayvan sahiplenme sürecini başlat

Bunlar hala kaynak odaklıdır. /orders/{id}/payment, bir siparişin ödeme kaynağını temsil eder.

Fiillerin Gerekli Göründüğü Durumlar

Bazı işlemler CRUD modeline uymaz. URL'lerde fiil kullanmadan bunları nasıl ele alacağınız aşağıda açıklanmıştır.

Arama İşlemleri

Yanlış:

GET /searchPets?query=labrador

Doğru Seçenek 1 (Sorgu Parametreleri):

GET /pets?search=labrador

Doğru Seçenek 2 (Arama Kaynağı):

GET /pets/search?q=labrador

Doğru Seçenek 3 (QUERY Metodu):

QUERY /pets
Content-Type: application/json

{
  "query": "labrador",
  "filters": {
    "status": "AVAILABLE"
  }
}

Modern PetstoreAPI, karmaşıklığa bağlı olarak bu üç deseni de destekler.

Hesaplamalar

Yanlış:

GET /calculateShipping?weight=10&destination=NY

Doğru:

GET /shipping-estimates?weight=10&destination=NY

Kaynak "gönderim tahminleri"dir, hesaplama eylemi değildir.

Toplu İşlemler

Yanlış:

POST /batchDeletePets

Doğru:

DELETE /pets?ids=1,2,3

Veya bir toplu işlem kaynağı kullanın:

POST /pets/batch-operations
Content-Type: application/json

{
  "operation": "delete",
  "ids": [1, 2, 3]
}

Durumu Değiştiren Eylemler

Yanlış:

POST /activateUser
POST /deactivateUser

Doğru:

PATCH /users/{id}
Content-Type: application/json

{
  "status": "ACTIVE"
}

Durum değişiklikleri kaynağın güncellemeleridir.

Apidog ile URL Tasarımını Test Etme

Apidog, REST API tasarımını doğrulamanıza ve URL'lerdeki fiil kullanımını yakalamanıza yardımcı olur.

Modern PetstoreAPI'yi İçe Aktar

1. Modern PetstoreAPI OpenAPI spesifikasyonunu içe aktarın
2. Apidog otomatik olarak test senaryoları oluşturur
3. Uç nokta yapısını ve adlandırmayı gözden geçirin

URL'lerdeki Fiilleri Kontrol Et

Apidog'da özel bir doğrulama kuralı oluşturun:

// URL'nin yaygın eylem fiillerini içerip içermediğini kontrol et
const verbs = ['get', 'create', 'update', 'delete', 'find', 'search',
               'calculate', 'process', 'send', 'fetch'];
const url = request.url.toLowerCase();

for (const verb of verbs) {
  if (url.includes(`/${verb}`)) {
    throw new Error(`URL contains verb: ${verb}. Use resource-oriented URLs instead.`);
  }
}

Uç Nokta Tutarlılığını Test Et

Apidog, ilgili uç noktaların tutarlı desenleri takip ettiğini doğrulayabilir:

✓ GET /pets
✓ POST /pets
✓ GET /pets/{id}
✓ PUT /pets/{id}
✓ DELETE /pets/{id}

Hepsi aynı temel kaynağı (/pets) kullanır.

Modern PetstoreAPI ile Karşılaştır

Modern PetstoreAPI'yi referans olarak kullanın:

1. Hem API'nizi hem de Modern PetstoreAPI'yi Apidog'a içe aktarın
2. Uç nokta yapılarını yan yana karşılaştırın
3. Tutarsızlıkları ve fiil kullanımını belirleyin
4. API'nizi REST prensiplerine uygun olarak yeniden düzenleyin

Geçiş Stratejileri

URL'lerinde fiiller içeren mevcut bir API'niz varsa, nasıl geçiş yapacağınız aşağıda açıklanmıştır.

Strateji 1: Sürümleme

Doğru URL'lerle yeni bir API sürümü oluşturun:

# Eski API (v1)
GET /api/v1/findPetsByStatus?status=available

# Yeni API (v2)
GET /api/v2/pets?status=available

Geriye dönük uyumluluk için v1'i koruyun, v2'ye geçişi teşvik edin.

Strateji 2: Takma Ad Kullanımı

Geçici olarak hem eski hem de yeni URL'leri destekleyin:

# Eski URL (kullanımdan kaldırıldı)
GET /pet/findByStatus?status=available

# Yeni URL (tercih edilen)
GET /pets?status=available

Yanıtlarla birlikte kullanımdan kaldırma uyarıları döndürün:

{
  "data": [...],
  "warnings": [
    {
      "code": "DEPRECATED_ENDPOINT",
      "message": "Bu uç nokta kullanımdan kaldırıldı. Bunun yerine GET /pets?status=available kullanın.",
      "sunset": "2027-01-01"
    }
  ]
}

Strateji 3: Yönlendirmeler

Basit geçişler için HTTP 301 yönlendirmelerini kullanın:

GET /pet/findByStatus?status=available
→ 301 Kalıcı Olarak Taşındı
Konum: /pets?status=available

Bu, GET istekleri için çalışır ancak POST, PUT veya DELETE için çalışmaz.

Sonuç

REST API URL'leri eylemler (fiiller) yerine isimler (kaynaklar) içermelidir. HTTP metotları fiilleri sağlar. Bu prensip tutarlı, ölçeklenebilir ve bakımı kolay API'ler oluşturur.

Eski Swagger Petstore, /pet/findByStatus gibi uç noktalarla bunu ihlal etmiştir. Modern PetstoreAPI, baştan sona kaynak odaklı URL'ler kullanarak bunu düzeltir: /pets?status=AVAILABLE.

Temel çıkarımlar:

• URL'lerde isimler kullanın: /pets, /orders, /users
• HTTP metotlarının fiiller olmasına izin verin: GET, POST, PUT, DELETE
• Filtreleme için sorgu parametreleri kullanın: /pets?status=available
• Karmaşık işlemler için alt kaynaklar kullanın: /orders/{id}/payment
• URL'lerdeki fiil kullanımını erken yakalamak için API tasarımınızı Apidog ile test edin

Kaynak odaklı URL tasarımının tam örnekleri için Modern PetstoreAPI dokümantasyonuna göz atın.

Sıkça Sorulan Sorular

REST URL'lerinde hiç fiil kullanabilir miyim?

Nadir durumlarda. Bir işlem gerçekten kaynak modeline uymuyorsa (/search veya /login gibi), bir fiil kabul edilebilir olabilir. Ancak %95 oranında, bunu bir kaynak olarak modelleyebilirsiniz.

/login ve /logout ne olacak?

Bunlar yaygın istisnalardır. Birçok API /auth/login ve /auth/logout kullanır. Alternatif olarak, bunları kaynak olarak modelleyin: POST /sessions (giriş) ve DELETE /sessions/{id} (çıkış).

Karmaşık sorguları nasıl ele alırım?

Basit filtreleme için sorgu parametreleri kullanın: /pets?status=available&species=dog. Karmaşık sorgular için QUERY HTTP metodunu veya bir arama kaynağı kullanın: POST /pets/search.

İşlemim CRUD'ye eşleşmezse ne olur?

Bunu bir alt kaynak olarak modelleyin. POST /processPayment yerine POST /orders/{id}/payment kullanın. Ödeme, siparişle ilgili bir kaynaktır.

URL'lerimin kaynak odaklı olup olmadığını nasıl test ederim?

OpenAPI spesifikasyonunuzu içe aktarmak ve URL'lerdeki fiilleri kontrol etmek için Apidog'u kullanın. API yapınızı referans olarak Modern PetstoreAPI ile karşılaştırın.

/pets/search mi yoksa /pets?search=query mi kullanmalıyım?

Her ikisi de kabul edilebilir. /pets?search=query temel arama için daha basittir. /pets/search veya QUERY /pets, birden çok parametre içeren karmaşık aramalar için daha iyi çalışır.

Fiil tabanlı URL'lerden nasıl geçiş yaparım?

API sürümleme (/v1/findPets yerine /v2/pets) kullanın, kullanımdan kaldırma uyarıları ekleyin ve istemcilere geçiş yapmaları için zaman tanıyın. Ayrıntılar için Geçiş Stratejileri bölümüne bakın.

Modern PetstoreAPI URL'lerde herhangi bir fiil kullanıyor mu?

Modern PetstoreAPI, URL'lerde fiil kullanmaktan kaçınır. Arama, filtreleme ve kimlik doğrulama gibi işlemler kaynaklar olarak modellenir veya sorgu parametreleri kullanır. Örnekler için REST API dokümantasyonunu kontrol edin.