# RESTful API Tasarımında En İyi Pratikler

> REST API tasarımında dikkat edilmesi gereken best practice'ler: endpoint isimlendirme, HTTP metodları, versiyonlama, hata yönetimi ve güvenlik.

**URL:** https://ekolsoft.com/tr/b/restful-api-tasariminda-en-iyi-pratikler

---

# 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.