Hap Bilgi 14: RESTful API Tasarımı - Geliştiriciler İçin Kapsamlı Rehber

Developer hap bilgi sever; 14. bölüm: RESTful API Tasarımı - Geliştiriciler İçin Kapsamlı Rehber. Modern yazılım geliştirmede API’ler uygulamalarımızın omurgasını oluşturuyor. İyi tasarlanmış bir RESTful API, hem geliştirici deneyimini iyileştirir hem de sistemin uzun vadeli sürdürülebilirliğini sağlar. Bu yazıda, profesyonel düzeyde RESTful API tasarımı için kritik olan 8 ana prensipten bahsedeceğiz.

1. 🏗️ Domain Model Driven Tasarım

API’nizin yol yapısını domain modelinize göre kurgulamak, tutarlı ve anlaşılır bir yapı oluşturmanın temelidir.

Neden Önemli?
Domain model odaklı tasarım, API’nizin iş mantığını doğrudan yansıtmasını sağlar. Bu yaklaşım, hem geliştiricilerin hem de API kullanıcılarının sistemi daha kolay anlamasını mümkün kılar.

Doğru Yaklaşım:

GET /api/users/{id}/orders
GET /api/orders/{id}/items
GET /api/products/{id}/reviews

Yanlış Yaklaşım:

GET /api/getUserOrders?userId=123
GET /api/getOrderItems?orderId=456
GET /api/getProductReviews?productId=789

Pratik Uygulama:
E-ticaret sisteminde kullanıcı, sipariş ve ürün arasındaki ilişkileri API yollarınızda net bir şekilde ifade edin. Kaynak hiyerarşisini koruyarak, alt kaynakları ana kaynaklarının altında organize edin.

2. 🔧 Doğru HTTP Metodlarını Seçin

HTTP metodları API’nizin davranışını belirler. Her metodun kendine özgü semantik anlamı vardır ve doğru kullanılmalıdır.

HTTP Metodları ve Kullanım Alanları:

GET /api/users/123
GET /api/products?category=electronics

POST /api/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

PUT /api/users/123
Content-Type: application/json

{
  "name": "John Smith",
  "email": "johnsmith@example.com"
}

DELETE /api/users/123

PATCH Metodunu Neden Kaçınmalısınız?
PATCH metodu kısmi güncelleme için tasarlanmış olsa da, uygulaması karmaşık ve tutarsızlıklara yol açabilir. Bunun yerine PUT metodunu kullanarak tam kaynak güncellemesi yapmak daha güvenli bir yaklaşımdır.

3. ⚡ İdempotence Prensibini Doğru Uygulayın

İdempotence, aynı isteğin birden fazla kez çalıştırılmasının tek seferde çalıştırılmasıyla aynı sonucu vermesi anlamına gelir.

Doğal İdempotent Metodlar:

• GET: Veri okuma işlemi yan etki oluşturmaz
• PUT: Aynı veri ile tekrar güncellemek sonucu değiştirmez
• DELETE: Zaten silinmiş bir kaynağı tekrar silmek hata vermez (404 yerine 200 döndürün)

POST İçin İdempotence Tasarımı:

POST /api/orders
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "userId": 123,
  "items": [{"productId": 456, "quantity": 2}]
}

Sunucu tarafında Idempotency-Key’i kontrol ederek, aynı key ile gelen istekleri tekrar işlemek yerine önceki sonucu döndürün.

4. 📊 Doğru HTTP Status Kodlarını Kullanın

Karmaşık status kod sistemleri yerine, sınırlı ve anlamlı bir set kullanın.

Temel Status Kodları:

2xx - Başarılı İşlemler

• 200 OK: Başarılı GET, PUT, DELETE
• 201 Created: Başarılı POST ile yeni kaynak oluşturma
• 204 No Content: Başarılı DELETE veya PUT, döndürülecek veri yok

4xx - İstemci Hataları

• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 422 Unprocessable Entity

5xx - Sunucu Hataları

• 500 Internal Server Error
• 503 Service Unavailable

Örnek Hata Yanıtı:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Geçersiz email formatı",
    "details": {
      "field": "email",
      "value": "invalid-email"
    }
  }
}

5. 🔄 Versiyonlama Stratejisi

URL Tabanlı Versiyonlama (Önerilen):

GET /api/v1/users/123
GET /api/v2/users/123

Header Tabanlı Versiyonlama:

GET /api/users/123
Accept: application/vnd.api+json;version=1

Versiyonlama Kuralları:

• Major: Breaking changes (v1, v2)
• Minor: Yeni özellikler (v1.1)
• Patch: Hata düzeltmeleri (v1.1.1)

Deprecation Stratejisi:

{
  "data": {...},
  "warnings": [
    {
      "type": "deprecation",
      "message": "Bu endpoint v3.0'da kaldırılacak",
      "sunset_date": "2025-12-31"
    }
  ]
}

6. 🛤️ Semantik Yol Tasarımı

Kaynak Odaklı Yaklaşım:

/api/users
/api/users/123
/api/users/123/orders
/api/users/123/orders/456

Fiil Yerine İsim Kullanın:

# Doğru
GET /api/users/123/orders

# Yanlış
GET /api/users/123/getOrders

Tutarlı Çoğul Kullanımı:

/api/users
/api/products
/api/orders

Özel Durumlar İçin Alt Kaynaklar:

POST /api/users/123/password/reset
POST /api/orders/456/payment/process
GET /api/users/123/dashboard/summary

7. 🔄 Batch Processing Tasarımı

Çoklu Kaynak Oluşturma:

POST /api/users/batch
Content-Type: application/json

{
  "items": [
    {"name": "John", "email": "john@example.com"},
    {"name": "Jane", "email": "jane@example.com"}
  ]
}

Çoklu Kaynak Güncelleme:

PUT /api/products/batch
Content-Type: application/json

{
  "items": [
    {"id": 123, "price": 29.99},
    {"id": 124, "price": 39.99}
  ]
}

Batch Yanıt Formatı:

{
  "success": true,
  "processed": 2,
  "failed": 0,
  "results": [
    {
      "id": 123,
      "status": "success",
      "data": {"id": 123, "name": "John"}
    },
    {
      "id": 124,
      "status": "error",
      "error": {"code": "VALIDATION_ERROR", "message": "Geçersiz email"}
    }
  ]
}

8. 🔍 Sorgu Dili Tasarımı

Pagination:

GET /api/users?page=2&limit=20
GET /api/users?offset=40&limit=20

Sorting:

GET /api/users?sort=name
GET /api/users?sort=-created_at
GET /api/users?sort=name,-age

Filtering:

GET /api/users?status=active
GET /api/users?age_gte=18&age_lt=65
GET /api/products?category=electronics&price_range=100-500

Field Selection:

GET /api/users?fields=id,name,email
GET /api/users?include=orders,profile

Gelişmiş Sorgular:

GET /api/users?search=john&filters[status]=active&filters[department]=engineering

Sorgu Yanıt Formatı:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 156,
    "pages": 8,
    "has_next": true,
    "has_prev": true
  },
  "filters": {
    "applied": {"status": "active"},
    "available": ["status", "department", "role"]
  }
}

🎯 Sonuç

Bu 8 prensip, RESTful API tasarımında temel taşları oluşturur. İyi tasarlanmış bir API:

• Geliştiriciler için öğrenme eğrisini azaltır
• Sistem entegrasyonlarını kolaylaştırır
• Uzun vadeli bakım maliyetlerini düşürür
• Kullanıcı deneyimini iyileştirir

API tasarımınızda bu prensipleri uygulamak, hem mevcut projenizin başarısını artıracak hem de gelecekteki geliştirmeler için sağlam bir temel oluşturacaktır. Unutmayın, iyi bir API tasarımı bir kez yapılan iş değil, sürekli geliştirilen bir süreçtir.

📚 Ek Kaynaklar

• API dokumentasyonu için OpenAPI/Swagger kullanın
• Rate limiting ve throttling uygulayın
• Güvenlik için HTTPS, authentication ve authorization mekanizmalarını ihmal etmeyin
• Monitoring ve logging ile API performansını takip edin
• API testing stratejinizi oluşturun ve otomatize edin