API Tasarımında ProblemDetails ve 4xx Durum Kodları

API Hata Yönetimi 101: ProblemDetails ve 4xx Durum Kodları

API'ler, modern uygulamaların bel kemiğidir. Kullanıcı girişinden, bir e-ticaret sitesinde sepete ürün eklemeye kadar her şey, ön yüz (frontend) ve arka yüz (backend) arasındaki API çağrılarıyla gerçekleşir. Her şey yolunda gittiğinde sorun yoktur, peki ya işler ters giderse? "Bir hata oluştu" gibi genel mesajlar, geliştiriciler ve son kullanıcılar için kafa karıştırıcı olabilir. İşte bu noktada, API'lerde standart ve etkili bir hata yönetimi stratejisine ihtiyacımız var.

Bu yazıda, web API'lerinde hata yönetiminin en önemli araçlarından biri olan ProblemDetails kavramını ve bununla birlikte kullanılan HTTP durum kodlarını ele alacağız.

Sorun: Vague (Belirsiz) Hata Mesajları

Bir API ucunun yalnızca 200 OK (başarılı) veya 500 Internal Server Error (beklenmedik hata) döndürmesi yeterli değildir. Örneğin, bir kayıt formunda kullanıcı, e-posta adresini yanlış formatta girdiğinde, arka yüzün sadece 500 hatası dönmesi yanlıştır. Neden mi? Çünkü bu bir sunucu hatası değil, istemcinin (kullanıcının) yaptığı bir hatadır. Doğru yaklaşım, istemciye "gönderdiğiniz veri hatalı" demek ve bu hatanın nedenini açıklamaktır.

API'ler, istemci hatalarını ve sunucu hatalarını net bir şekilde ayırmalıdır. Bu ayrım için de 4xx ve 5xx durum kodları kullanılır.

Çözüm: ProblemDetails ile Hatalara Bir Kimlik Verin

ProblemDetails (RFC 7807), API'lerden gelen hata yanıtları için standart bir JSON formatıdır. Bu standart, hatanın sadece durum kodunu değil, aynı zamanda başlık, detay ve diğer ilgili bilgileri de içerir. Bu sayede, ön yüz uygulaması hatanın nedenini kolayca anlayabilir ve kullanıcıya özel bir mesaj gösterebilir.

4xx Hataları: İstemcinin Kontrol Edebileceği Hatalar

4xx ile başlayan HTTP durum kodları, istemciden kaynaklanan hataları işaret eder. ProblemDetails bu hataları açıklamak için mükemmeldir.

1. 400 Bad Request - Geçersiz İstek

Bu kod, istemcinin gönderdiği verinin hatalı, eksik veya beklenen formatta olmadığını belirtir. En sık form doğrulama (validation) hataları için kullanılır.

• Senaryo: Bir kayıt formunda, kullanıcı adı boş bırakıldı veya e-posta formatı yanlış girildi.

public IResult GecersizVeriGonderimi()
{
    // Örnek bir model doğrulama hatası oluşturulur.
    return Results.ValidationProblem(new Dictionary
    {
        {"KullaniciAdi", new[] {"Kullanıcı adı en az 5 karakter olmalıdır."}},
        {"Email", new[] {"Geçerli bir e-posta adresi giriniz."}}
    });
}

2. 404 Not Found - Kaynak Bulunamadı

Bu kod, istemcinin erişmeye çalıştığı kaynağın (ürün, kullanıcı, dosya vb.) sunucuda bulunmadığını belirtir.

• Senaryo: Kullanıcı, var olmayan bir ürün ID'si ile ürün detaylarını görüntülemeye çalışıyor.

public IResult KaynakBulunamadi(int id)
{
    // Belirli bir ID'ye sahip kaynağın bulunamadığı varsayılır.
    return Results.NotFound(new
    {
        title = "Kaynak Bulunamadı",
        detail = $"'{id}' ID'li kaynak veritabanında mevcut değil."
    });
}

3. 409 Conflict - Çakışma

Bu kod, istemcinin isteğinin, sunucudaki mevcut bir durumla çakışması sonucunda iş kuralı ihlali meydana geldiğinde kullanılır.

• Senaryo: Satışı durdurulmuş bir ürünü sepete ekleme veya zaten kullanılmış bir kullanıcı adıyla kayıt olma.

public IResult KuralIhlali()
{
    // Bir iş kuralının ihlal edildiği varsayılır (örn: stokta ürün yok).
    return Results.Conflict("Bu ürünün stoğu tükenmiştir.");
}

4. 401 Unauthorized - Yetkisiz Erişim

Bu kod, istemcinin kimlik bilgilerini (örneğin, API anahtarı veya JWT) sağlamadığını veya sağladığı bilgilerin geçersiz olduğunu belirtir. Yani, kimlik doğrulama (authentication) başarısız olmuştur.

• Senaryo: Bir kullanıcı, giriş yapmadan veya geçerli bir token olmadan gizli bir API ucuna erişmeye çalışıyor.

public IResult YetkisizErisim()
{
    var problem = new ProblemDetails
    {
        Title = "Kimlik Doğrulama Gerekli",
        Detail = "Bu kaynağa erişmek için geçerli bir API anahtarı sağlamalısınız.",
        Status = StatusCodes.Status401Unauthorized
    };
    return Results.Problem(problem);
}

5. 403 Forbidden - Yasaklı Erişim

Bu kod, istemcinin kimliğinin doğrulandığını ancak istenen kaynağa veya işleme erişim izni olmadığını belirtir. Yani, kullanıcı sisteme girmiştir ancak yetkilendirme (authorization) sorunu vardır.

• Senaryo: Bir yönetici paneli API'sine, yönetici olmayan bir kullanıcının erişmeye çalışması.

public IResult YasakliErisim()
{
    var problem = new ProblemDetails
    {
        Title = "Erişim Reddedildi",
        Detail = "Bu işlemi gerçekleştirmek için gerekli yetkiye sahip değilsiniz. Lütfen yöneticinize başvurun.",
        Status = StatusCodes.Status403Forbidden
    };
    return Results.Problem(problem);
}

5xx Hataları: Sunucunun Kontrol Etmesi Gereken Hatalar

5xx ile başlayan HTTP durum kodları, API'nin kendi içinde oluşan ve istemciden bağımsız olan beklenmedik hataları gösterir. Bu hatalar, veritabanı bağlantı sorunları, sunucu çökmeleri veya kodunuzdaki öngörülemeyen hatalardan kaynaklanabilir. ProblemDetails bu hatalarla kullanılmaz.

• Güvenlik: 500 hatasının detayları (hata izi, veritabanı şeması vb.) hassas bilgiler içerir. Bu bilgilerin istemciye sızdırılması büyük bir güvenlik riskidir.

Peki, Hataları Nasıl İzleyeceğiz?

İşte bu noktada loglama sistemleri devreye girer. Bir hata oluştuğunda:

1. Arka yüz (API): Hatanın tüm detaylarını (hata izi, ilgili istek verileri vb.) güvenli bir loglama servisine (örn; OpenTelemetry, Sentry) kaydeder.
2. Arka yüz (API): Ön yüze sadece 500 durum kodunu döner.
3. Ön yüz (Frontend): 500 kodunu aldığında, kullanıcıya “Bir hata oluştu, lütfen daha sonra tekrar deneyin.” gibi genel ve dostça bir mesaj gösterir.
4. Arka yüz ekibi: Loglama sistemi, geliştiricileri anında uyarır ve hatanın kaynağını kolayca tespit etmelerini sağlar.

Bu yaklaşım, hem uygulamanızı güvende tutar hem de hata ayıklama süreçlerini hızlandırır.

Özet: Ne Zaman Ne Kullanılır?

CRUD Operasyonları ve HTTP Durum Kodları

RESTful API tasarımında, her bir CRUD işlemi için doğru HTTP durum kodunu kullanmak, API'yi daha anlaşılır ve öngörülebilir hale getirir. İşte yaygın senaryolar ve onlara karşılık gelen durum kodları: