Tutarlı API Nasıl Tasarlanır?

Backend geliştirmede çoğu zaman odak noktası “çalışıyor mu?” sorusu oluyor. Oysa gerçek kalite, sistemin öngörülebilir ve tutarlı davranmasında ortaya çıkar.

Bir API’nin doğru tasarlanması, sadece veri döndürmesiyle değil; uzun vadede değişime ne kadar dayanıklı olduğu ile ölçülür.

Bu yazıda, bir endpoint tasarlarken özellikle dikkat ettiğim temel prensipleri paylaşıyorum.

HTTP Standartlarına Sadık Kalmak

HTTP zaten bir sözleşmedir.

• 200 OK → Başarılı
• 201 Created → Kaynak oluşturuldu
• 400 Bad Request → İstek hatalı
• 401 Unauthorized → Kimlik doğrulama yok
• 403 Forbidden → Yetki yok
• 404 Not Found → Kaynak yok
• 500 Internal Server Error → Sunucu hatası

Her durumda 200 dönmek, istemci tarafında belirsizlik oluşturur. Status code doğru kullanılmadığında, API’nin semantiği bozulur.

Response Formatında Tutarlılık

Frontend entegrasyonlarında en çok sorun çıkaran şeylerden biri response tutarsızlığıdır.

Örneğin:

Başarılı durumda:

{
  "data": { ... },
  "success": true
}

Hata durumunda:

{
  "error": "Bir hata oluştu"
}

Bu yapı uzun vadede karmaşaya yol açar.

Daha sağlıklı bir yaklaşım:

{
  "success": false,
  "data": null,
  "errors": ["Validation failed"]
}

Tutarlı response formatı:

• Client tarafını sadeleştirir
• Debug sürecini kolaylaştırır
• Dokümantasyonu netleştirir

Domain Model ile Dış Dünya Arasına DTO Koymak

Entity’yi doğrudan dışarı açmak risklidir. Peki neden ?

• Fazladan alan sızabilir
• Internal yapı dış dünyaya bağımlı hale gelir
• Refactor süreci zorlaşır

DTO kullanmak:

• Güvenlik sağlar
• Bağımlılığı azaltır
• Versiyonlama sürecini kolaylaştırır

Backend tarafında izolasyon en kritik prensiplerden biridir.

Exception’ları Merkezi Yönetmek

Her controller’da try-catch blokları yazmak hem tekrardır hem de kontrolü dağıtır.

Global exception middleware:

• Tek noktadan hata yönetimi sağlar
• Standart error response üretir
• Loglama sürecini düzenler

Bu yaklaşım sistem büyüdükçe ciddi fark yaratır.

Versiyonlamayı Baştan Düşünmek

Bir API zamanla değişir.
Yeni alan eklenir, eski davranışlar güncellenir.

Eğer baştan versiyonlama düşünülmemişse:

• Eski client’lar kırılır
• Mobil uygulamalar sorun yaşar
• Entegrasyonlar bozulur

/api/v1/... gibi bir yapı küçük bir detay gibi görünse de
uzun vadede büyük bir güvenlik sağlar.

Kod yazmak kolaydır. Ama tutarlı, sürdürülebilir ve öngörülebilir bir sistem tasarlamak zordur. Gerçek seviye, endpoint yazabilmek değil; büyüyebilen bir API tasarlayabilmektir.