REST API Tasarımında İyi Uygulamalar

Bir API tasarlamak, sadece endpoint yazmaktan ibaret değil. İyi tasarlanmış bir REST API; geliştiricilerin işini kolaylaştırır, sistemin uzun ömürlü olmasını sağlar ve bakım maliyetini ciddi ölçüde düşürür. Yıllar içinde farklı projelerde API geliştirirken öğrendiklerimi bu yazıda derledim.

1. Kaynak Odaklı URL Yapısı Kurun

REST'in temel felsefesi kaynaklar (resources) üzerine kuruludur. URL'ler fiil değil, isim içermelidir.

Yanlış:

• GET /getUsers
• POST /createOrder

Doğru:

• GET /users
• POST /orders

Kaynaklar arasındaki ilişkileri ise hiyerarşik bir yapıyla ifade edin:

• GET /users/{id}/orders → Belirli bir kullanıcının siparişleri
• GET /orders/{id}/items → Siparişteki ürünler

2. HTTP Metodlarını Doğru Kullanın

Her HTTP metodunun anlamsal bir amacı vardır; buna sadık kalmak, API'nizi tahmin edilebilir kılar:

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

Özellikle PUT ile PATCH ayrımı sıkça karıştırılır. PUT ile isteği gönderdiğinizde, gönderilmeyen alanlar boş/sıfır kabul edilir. PATCH ise yalnızca belirtilen alanları günceller.

3. HTTP Durum Kodlarını Anlamlı Kullanın

Her şeye 200 OK dönmek, istemci tarafında gereksiz iş yükü yaratır. Sık kullanılan durum kodlarını doğru eşleştirin:

• 200 OK – Başarılı GET, PUT, PATCH
• 201 Created – Başarılı POST
• 204 No Content – Başarılı DELETE
• 400 Bad Request – Geçersiz istek gövdesi
• 401 Unauthorized – Kimlik doğrulama gerekli
• 403 Forbidden – Yetki yetersiz
• 404 Not Found – Kaynak bulunamadı
• 409 Conflict – Veri çakışması
• 500 Internal Server Error – Sunucu hatası

4. Sürümleme (Versioning) Stratejisi Belirleyin

API'niz bir gün değişecek; bu kaçınılmaz. Geriye dönük uyumluluğu korumak için sürümleme şarttır. En yaygın ve temiz yöntem URL tabanlı sürümlemedir:

• https://api.siteniz.com/v1/users
• https://api.siteniz.com/v2/users

Alternatif olarak Accept: application/vnd.siteniz.v2+json gibi başlık tabanlı sürümleme de kullanılabilir; ancak URL tabanlı yaklaşım test ve dokümantasyon açısından çok daha pratiktir.

5. Sayfalama, Filtreleme ve Sıralama Sunun

Büyük veri setlerini tek seferde döndürmek hem performans hem de kullanıcı deneyimi açısından kötüdür. Standart bir yapı benimseyin:

• Sayfalama: GET /products?page=2&limit=20
• Filtreleme: GET /products?category=elektronik&inStock=true
• Sıralama: GET /products?sort=price&order=asc

6. Tutarlı ve Anlamlı Hata Yanıtları Döndürün

Hata mesajları geliştiricinin en iyi arkadaşıdır. Belirsiz veya eksik hata yanıtları, hata ayıklama sürecini gereksiz yere uzatır. Standart bir hata yapısı belirleyin ve ona sadık kalın:

{
  "status": 400,
  "error": "VALIDATION_ERROR",
  "message": "E-posta adresi geçerli değil.",
  "field": "email"
}

7. Güvenliği Baştan Planlayın

• Her zaman HTTPS kullanın.
• Kimlik doğrulama için JWT veya OAuth 2.0 tercih edin.
• Rate limiting uygulayarak API'nizi aşırı yüklenmeye karşı koruyun.
• Hassas verileri (şifre, kart numarası vb.) yanıtta asla döndürmeyin.

---

İyi bir REST API; tutarlı, öngörülebilir ve geliştiriciye saygılıdır. Yukarıdaki pratiklerin tamamını ilk sürümde mükemmel uygulamak zorunda değilsiniz; ancak en azından bir standart belirleyip ona sadık kalmak, ilerleyen süreçte çok büyük fark yaratacaktır. Kod yazıldığı kadar okunur ve kullanılır — bunu API tasarımında da unutmamak gerekiyor.