RESTful API Tasarımında En İyi Pratikler

Bir API'nin kalitesi, yalnızca çalışmasıyla değil; geliştiricilerin onu ne kadar kolaylıkla kullanabildiğiyle ölçülür. İyi tasarlanmış bir REST API, öngörülebilir, tutarlı ve self-documenting olmalıdır.

1. Kaynak Odaklı URL Tasarımı

REST'in temel felsefesi kaynaklara (resource) dayanır. URL'ler fiil değil, isim içermelidir:

❌ Kötü:
GET /getUsers
POST /createUser
DELETE /deleteUser/5

✅ İyi:
GET /users
POST /users
DELETE /users/5

2. HTTP Metodlarını Doğru Kullanmak

• GET — Kaynak okuma, yan etkisiz (idempotent)
• POST — Yeni kaynak oluşturma
• PUT — Kaynağın tamamını güncelleme
• PATCH — Kaynağın bir kısmını güncelleme
• DELETE — Kaynak silme

3. Anlamlı HTTP Status Kodları

Her yanıtta doğru HTTP status kodu kullanmak, API'nin davranışını tahmin edilebilir kılar:

• 200 OK — Başarılı GET, PUT, PATCH
• 201 Created — Başarılı POST, yeni kaynak oluşturuldu
• 204 No Content — Başarılı DELETE
• 400 Bad Request — Geçersiz istek gövdesi
• 401 Unauthorized — Kimlik doğrulama gerekli
• 403 Forbidden — Yetki yok
• 404 Not Found — Kaynak bulunamadı
• 422 Unprocessable Entity — Validation hatası
• 500 Internal Server Error — Sunucu hatası

4. API Versiyonlama

API'niz büyüdükçe breaking change'ler kaçınılmaz olur. Versiyonlama stratejisi baştan belirlenmeli:

// URL tabanlı versiyonlama (en yaygın)
GET /api/v1/users
GET /api/v2/users

// Header tabanlı
Accept: application/vnd.myapi.v2+json

5. Tutarlı Hata Yanıtı Formatı

Tüm hata yanıtları aynı formatta olmalıdır. RFC 7807 (Problem Details) standardı bu konuda iyi bir referanstır:

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "Email adresi geçerli değil",
  "errors": {
    "email": ["Geçerli bir email adresi giriniz"]
  }
}

6. Pagination ve Filtreleme

Büyük veri setleri için pagination zorunludur. Cursor-based pagination, offset tabanlıya kıyasla büyük tablolarda çok daha performanslıdır:

GET /users?page=2&pageSize=20
GET /users?cursor=eyJpZCI6MTAwfQ&limit=20
GET /users?status=active&sort=createdAt&order=desc

7. API Dokümantasyonu

OpenAPI (Swagger) standardı, API dokümantasyonu için sektörün ortak dili haline gelmiştir. ASP.NET Core'da Swashbuckle veya NSwag ile otomatik dokümantasyon oluşturulabilir.

Sonuç

İyi bir RESTful API tasarımı, frontend-backend ayrışmasını kolaylaştırır, entegrasyon süreçlerini hızlandırır ve teknik borcu azaltır. Bu pratikleri uygulamak, uzun vadede geliştirici deneyimini ve sistem güvenilirliğini önemli ölçüde artırır.