Dış sistemlere açtığım API’lerde uyduğum birkaç kural

B2B tarafında yazdığım API’lerin çoğunu ben değil, bir ERP, bir yönetim paneli ya da başka bir ekibin kodu kullanıyor. Bu yüzden API tasarımında asıl soru hep şu: bunu ilk kez gören biri yanlış kullanabilir mi? Zamanla oturmuş birkaç kuralım var.

1. Hata formatı tek tip olsun

İstemci tarafında en sinir bozucu şey, her endpoint’in hatayı farklı biçimde döndürmesidir. Bu yüzden tek bir zarf belirleyip ona sadık kalıyorum:

{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Sipariş bulunamadı.",
    "details": { "orderId": "1234" }
  }
}

code makine için (istemci ona göre dallanır), message insan için. Böylece istemci, mesaj metnini karşılaştırmak zorunda kalmıyor.

2. HTTP durum kodlarını doğru kullan

• 400 — istemci hatası, gönderdiğin veri yanlış.
• 401/403 — kimlik yok / yetki yok (ikisi farklı şey).
• 404 — kaynak yok.
• 409 — çakışma, örneğin aynı kaydı iki kez oluşturmaya çalışmak.
• 422 — format doğru ama iş kuralına takıldı.

Her şeye 200 döndürüp gövdeye "success": false yazmak, istemcinin işini zorlaştırmaktan başka işe yaramıyor.

3. Versiyonu baştan koy

/v1/ ile başlamanın hiçbir maliyeti yok. Sonradan kırıcı bir değişiklik gerektiğinde /v2/’yi yanına koyup eski istemcileri bozmadan geçiş yapabiliyorsun. Daha önce yayımladığın bir alanın tipini değiştirmek ise, karşı taraftaki entegrasyonu sessizce bozmanın en hızlı yolu.

4. Doğrulamayı sınırda yap

Girdiyi içeri girer girmez Zod ile doğruluyorum. İş mantığı katmanına asla doğrulanmamış veri ulaşmıyor — böylece service katmanı verinin temiz olduğunu varsayabiliyor.

---

Hiçbiri sihirli değil. Ama API’yi “benim kullanacağım kod” değil de “tanımadığım birinin entegre edeceği bir sözleşme” olarak düşününce, bu kararların hepsi kendiliğinden mantıklı geliyor.