API Response Standartları: Problem Details (RFC 7807)

API Response Standartları: Problem Details (RFC 7807)

HTTP API'lerinde bir hata oluştuğunda, istemciye yalnızca 404 Not Found veya 500 Internal Server Error dönmek yeterli değildir. İstemcinin hatanın ne olduğunu, neden oluştuğunu ve nasıl düzeltilebileceğini anlaması gerekir. Problem Details, HTTP API'leri için makine tarafından okunabilir (machine-readable) hata yanıtları tanımlayan bir spesifikasyondur .

1. RFC 7807 ve RFC 9457: Tarihsel Gelişim

Problem Details spesifikasyonu ilk olarak RFC 7807 (Mart 2016) ile tanımlanmıştır . Temmuz 2023'te ise RFC 9457 bu spesifikasyonun halefi olarak yayınlanmış ve RFC 7807'yi geçersiz kılmıştır .

RFC 9457'nin Getirdiği Yenilikler:

IANA Problem Types Registry: Yaygın kullanılan problem tipleri için merkezi bir kayıt defteri oluşturulmuştur .
Varsayılan Tip: about:blank: type üyesi belirtilmezse, about:blank varsayılan değer olarak kullanılır; bu, problemin HTTP durum kodunun ötesinde ek bir anlam taşımadığını gösterir .
Geriye Dönük Uyumluluk: RFC 9457, RFC 7807 ile tamamen geriye dönük uyumludur. Aynı alanlar ve aynı medya tipi (application/problem+json) korunmuştur .

Önemli Not: RFC 9457, RFC 7807'yi geçersiz kılmış olsa da, mevcut uygulamaların değiştirilmesi zorunlu değildir. Yeni projelerde RFC 9457 referans alınmalı, mevcut projelerde ise gerektiğinde güncellenmelidir.

2. Problem Details Nesnesinin Üyeleri

Problem Details nesnesi, aşağıdaki beş temel üyeden oluşur (tümü isteğe bağlıdır) :

Üye	Tip	Açıklama
`type`	URI	Problemin tipini tanımlayan benzersiz bir URI. Belirtilmezse varsayılan değeri `about:blank`'tır .
`title`	String	Problemin kısa, insan tarafından okunabilir özeti. `about:blank` kullanıldığında, HTTP durum kodunun önerilen ifadesiyle aynı olmalıdır .
`status`	Integer	HTTP durum kodu (ör. 403, 404, 500). Sadece bilgilendirme amaçlıdır; asıl durum kodu HTTP yanıt başlığındadır .
`detail`	String	Bu spesifik problem oluşumu için insan tarafından okunabilir açıklama. İstemcinin problemi düzeltmesine yardımcı olmalıdır .
`instance`	URI	Bu spesifik problem oluşumunu tanımlayan URI. Destek veya adli inceleme için kullanışlıdır .

Örnek Problem Details JSON Yanıtı:

json

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough credit.",
  "status": 403,
  "detail": "Your current balance is 30, but that costs 50.",
  "instance": "/account/12345/msgs/abc",
  "balance": 30,
  "accounts": ["/account/12345", "/account/67890"]
}

Bu örnekte balance ve accounts gibi genişletme üyeleri (extension members) eklenmiştir. Spesifikasyon, problem tipine özel ek alanların eklenmesine izin verir .

3. Güvenlik ve En İyi Pratikler

Problem Details, hata ayıklama bilgisi değil, istemcinin problemi anlamasına yardımcı olacak bilgiler içermelidir. Spesifikasyon, hassas bilgi sızıntısına karşı açıkça uyarır :

Stack trace göndermeyin: Sunucu uygulamasının iç detaylarını ifşa eder.
Veritabanı hata mesajları göndermeyin: Şema ve sistem bilgisi sızdırır.
İç sistem yolları ve sunucu isimleri göndermeyin.
status üyesine güvenmeyin: Proxy ve cache'ler bu üyeyi değiştirebilir; asıl durum kodu HTTP başlığıdır .

Genişletme Alanları: Problem tipine özel bilgiler (ör. balance, errors) extensions üzerinden eklenir. Bu alanlar, istemcinin hatayı programatik olarak işlemesini sağlar .

4. ASP.NET Core'da Problem Details Desteği

ASP.NET Core, Problem Details'i yerleşik olarak destekler.

A. Temel Yapılandırma:

csharp

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();
app.UseExceptionHandler();
app.UseStatusCodePages();

B. Otomatik ProblemDetails Üretimi:
[ApiController] attribute'ü ile işaretlenmiş controller'larda, NotFound(), BadRequest() gibi metotlar otomatik olarak ProblemDetails formatında yanıt üretir :

json

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "traceId": "0HLHLV31KRN83:00000001"
}

C. ValidationProblemDetails:
Model validasyon hataları için ValidationProblemDetails sınıfı kullanılır :

json

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Email": ["The Email field is not a valid e-mail address."],
    "Password": ["The Password must be at least 8 characters long."]
  },
  "traceId": "|7fb5e16a-4c8f23bbfc974667."
}

D. Özelleştirme:

csharp

builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = ctx =>
    {
        ctx.ProblemDetails.Extensions["traceId"] = ctx.HttpContext.TraceIdentifier;
    };
});

5. Medya Tipi ve XML Desteği

Problem Details için standart medya tipi application/problem+json'dır . RFC 7807 ayrıca XML formatı için application/problem+xml medya tipini de tanımlamıştır . Ancak modern API'lerde JSON formatı baskındır.

Sonuç

Problem Details (RFC 9457 / RFC 7807), HTTP API'lerinde hata yanıtlarını standartlaştırmak için endüstri standardı haline gelmiştir. Beş temel üye (type, title, status, detail, instance) ve genişletme alanları ile makine tarafından okunabilir, tutarlı ve bilgilendirici hata yanıtları oluşturmanıza olanak tanır. ASP.NET Core, AddProblemDetails() ve ValidationProblemDetails ile bu spesifikasyonu yerleşik olarak destekler. Güvenlik açısından, hata yanıtlarında hassas bilgi sızdırmamak kritik öneme sahiptir. Unutmayın: İyi bir hata yanıtı, istemcinin sorunu anlamasını ve düzeltmesini sağlar; kötü bir hata yanıtı ise destek ekibinizin saatlerini çalar.

İlgili yazılar