API hata gövdelerimi RFC 7807 problem+json biçimine mi taşımalıyım?

Kısa cevap: Evet, standartlaştırın.

Kısa cevap

Ama iki şart: 7807 yerine onu güncelleyen (obsolete eden) RFC 9457’yi baz alın ve bunu her endpoint’e elle değil, tek bir merkezi katmanda zorunlu kılın.

Neden

1. 7807 artık RFC 9457. Aynı şekil, 2023’te güncellendi. Yeni işlerde 9457’yi referans alın. Alanlar aynı: type (URI), title, status, detail, instance — ve istediğiniz kadar ekstra (extension) alan koyabilirsiniz.

2. Asıl kazanç alan isimleri değil, tek tip zarftır. İstemci ekipleri artık her serviste tek bir şekli parse eder. Sizin derdiniz zaten tam olarak buydu; standardın bütün değeri de burada. Yani evet, yapmaya değer.

Ne yapmalı

1. Content-Type’ı doğru set edin: application/problem+json. İstemciler ve ara proxy’ler bunu normal bir gövdeden ayırt edebilsin. Bu başlığı unutmak, standardı yarım uygulamaktır.

2. type stabil bir makine anahtarıdır — sözleşme gibi davranın. Bir URN ya da bir dokümantasyon URL’i kullanın. İstemci title/detail gibi insan-okunur alanlara değil, type’a göre dallanır. detail içine stack trace veya iç ayrıntı sızdırmayın; orası kullanıcıya dönük insan-okunur bir cümledir.

   {
     "type": "https://api.example.com/problems/insufficient-funds",
     "title": "Insufficient funds",
     "status": 422,
     "detail": "Cüzdan 7f3a bakiyesi 12.00, gereken 50.00.",
     "instance": "/wallets/7f3a/withdrawals/9910"
   }

3. Tek yerde zorunlu kılın — exception handler / middleware. Laravel’de (11’den beri bootstrap/app.php içindeki withExceptions()->render(), öncesinde Handler’ın render katmanı), Go’da merkezi bir “error → problem” mapper’da üretin. Her endpoint’te ayrı ayrı yazarsanız zamanla drift başlar; standardın anlamı da kaçar.

4. Validation hataları için extension gerekir. 9457 alan-bazlı hata listesi tanımlamaz. Doğrulama için bir errors dizisi extension’ı ekleyin ve bu şekli bir kez tüm servislerde sabitleyin — yoksa yine servis başına farklılaşır.

5. Geçişi geriye dönük uyumlu planlayın. Mevcut istemciler eski gövdeyi bekliyor olabilir. Sunucu tarafında yeni biçime geçmek kolay ama istemciler bir gecede güncellenmez. Yeni problem+json biçimini bir API sürümüne bağlayın ya da geçiş penceresinde her iki alanı da (örneğin eski message ile yeni detail) bir süre birlikte döndürün; istemciler taşındıkça eskisini kaldırın.

6. Her şeyi standarda boğmayın. problem+json hata gövdeleri içindir; başarılı yanıtların şeklini değiştirmez. Ayrıca dokümantasyonu da otomatikleştirin: OpenAPI şemanızda type kataloğunu referans olarak tanımlayın ki istemciler hangi hata tiplerini bekleyeceklerini sözleşmeden görsün.

Sonuç: Ben olsam 9457’yi baz alır, type için versiyonlanabilir bir URI şeması belirler, üretimi tek bir exception handler’a toplar ve validation için ortak bir errors extension’ı tanımlardım. Migrasyonu da tek seferde değil, type kataloğunu doldururken ve istemcileri taşırken kademeli yapardım. Standardın değeri disiplinde: tek zarf, tek üretim noktası, type’ı sözleşme gibi yönetmek.