REST API Tasarımında İyi Uygulamalar

Bir API tasarlarken verdiğiniz kararlar, hem sizin hem de o API'yi kullanacak geliştiricilerin hayatını doğrudan etkiler. Yıllar içinde onlarca servis entegrasyonu yaparken gördüm ki kötü tasarlanmış bir API, projenin en büyük teknik borcu hâline gelebiliyor. Bu yazıda REST API tasarımında beni en çok kurtaran iyi uygulamaları paylaşacağım.

1. Kaynak Adlarını Doğru Seçin

REST'in temeli kaynaklardır. URL'leriniz fiil değil, isim içermeli:

• ❌ /getUsers, /deleteProduct
• ✅ /users, /products

Çoğul isimler tutarlılığı artırır. Koleksiyon için /users, tekil kaynak için /users/{id} kullanın. Basit ama şaşırtıcı derecede çok ihlal edilen bir kural.

2. HTTP Metodlarını Amaçlarına Göre Kullanın

| Metod | Amaç | |-------|------| | GET | Kaynak okuma | | POST | Yeni kaynak oluşturma | | PUT | Kaynağı tamamen güncelleme | | PATCH | Kaynağı kısmen güncelleme | | DELETE | Kaynağı silme |

POST ile her şeyi yapmaya çalışmak sizi kısa vadede kurtarır, uzun vadede boğar. HTTP'nin semantiğini kullanan bir API, hem önbellekleme hem de dokümantasyon açısından çok daha anlaşılır olur.

3. Anlamlı HTTP Durum Kodları Döndürün

Her şey için 200 OK ya da 500 Internal Server Error döndürmek yanlış. Doğru durum kodları, istemci tarafındaki hata yönetimini kolaylaştırır:

• 201 Created → Başarılı kaynak oluşturma
• 204 No Content → Başarılı silme
• 400 Bad Request → Geçersiz istek gövdesi
• 401 Unauthorized → Kimlik doğrulama hatası
• 403 Forbidden → Yetki hatası
• 404 Not Found → Kaynak bulunamadı
• 422 Unprocessable Entity → Validasyon hatası
• 429 Too Many Requests → Rate limit aşımı

4. Tutarlı ve Bilgilendirici Hata Yanıtları

Hata mesajı olarak yalnızca HTTP kodu döndürmek yetmez. İstemciye ne olduğunu açıklayan yapılandırılmış bir gövde şarttır:

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

Tutarlı bir hata formatı, hem front-end ekibinin hem de harici entegrasyon yapanların işini ciddi ölçüde kolaylaştırır.

5. Versiyonlama Stratejisi Belirleyin

API'niz büyüdükçe breaking change kaçınılmaz olur. Bunu yönetmenin en yaygın ve sağlıklı yolu URL versiyonlamasıdır:

/api/v1/users
/api/v2/users

Header tabanlı versiyonlama da tercih edilebilir, ancak URL versiyonlaması debug ve log takibini çok daha kolay kılar.

6. Sayfalama, Filtreleme ve Sıralama

Koleksiyon endpoint'lerini tasarlarken şu parametreleri standart hâle getirin:

• Sayfalama: ?page=2&limit=20 ya da cursor tabanlı
• Filtreleme: ?status=active&role=admin
• Sıralama: ?sort=createdAt&order=desc

Yanıtta meta bilgisini de mutlaka döndürün:

{
  "data": [...],
  "meta": {
    "total": 340,
    "page": 2,
    "limit": 20
  }
}

7. Güvenliği İhmal Etmeyin

• Her endpoint'te kimlik doğrulama (JWT, OAuth 2.0) zorunlu olsun.
• Rate limiting uygulayın; kötü niyetli ya da hatalı istemcilere karşı ilk savunma hattınız budur.
• HTTPS dışında hiçbir kanal desteklemeyin.
• Hassas veriyi (şifre hash'i, internal ID'ler) response'a asla dahil etmeyin.

8. Dokümantasyonu Koddan Ayrı Tutmayın

OpenAPI (Swagger) standartını benimseyerek dokümantasyonu koda entegre edin. Güncelliğini yitirmiş bir API dökümantasyonu, olmayan dokümantasyondan daha tehlikelidir; çünkü geliştiricileri yanlış yönlendirir.

---

REST API tasarımı bir kez yapılıp geçilen bir şey değil, projeyle birlikte evrilen bir süreç. Yukarıdaki prensipleri erken benimsemek, ileride ödeyeceğiniz teknik borcu önemli ölçüde azaltır. Sonraki yazımda GraphQL ile REST'i karşılaştıracağım; hangi senaryoda hangisini tercih ettiğimi anlatacağım.