HTTP durum kodları ve doğru cevap dönmek: IActionResult ve Results

Bir önceki yazıda ilk controller'ımızı yazdık ve cevap dönerken Ok ile NotFound gibi yardımcıları şöyle bir kullandık. Bugün o yardımcıların arkasındaki mantığa, yani HTTP durum kodlarına odaklanıyoruz. Çünkü doğru veriyi dönmek işin yarısı; o veriyi doğru durum koduyla dönmek diğer yarısı. Bir API'yi profesyonel yapan detay çoğu zaman tam olarak burada gizlidir.

Durum Kodu Neden Bu Kadar Önemli?

Her HTTP cevabının başında üç haneli bir sayı bulunur. Bu sayı, isteğin sonucunu tek bakışta özetler. İsteği yapan taraf, cevabın gövdesini okumaya gerek kalmadan sadece bu sayıya bakarak ne olduğunu anlayabilir. İşlem başarılı mı oldu, aradığı şey bulunamadı mı, yoksa gönderdiği veride bir sorun mu var; hepsi bu küçük sayıda saklı.

Şunu bir düşün: bir mobil uygulama senin API'ne bir istek gönderdi ve sen her durumda 200 döndürdün, hata olsa bile. O zaman uygulama, bir şeyin ters gittiğini nasıl anlayacak? Cevabın içine bakıp metni ayrıştırmak zorunda kalır ki bu hem kırılgan hem de zahmetli. Oysa 404 dönseydin, uygulama tek satırla "kaynak bulunamadı" diyebilirdi. Durum kodları, taraflar arasındaki ortak ve net bir dildir.

En Sık Kullanılan Durum Kodları

Onlarca durum kodu var ama günlük hayatta bir avuç tanesi işinin büyük kısmını görür. Kodlar mantıklı gruplara ayrılmıştır: 2 ile başlayanlar başarı, 4 ile başlayanlar istemci hatası, 5 ile başlayanlar sunucu hatasıdır. En çok karşılaşacakların şunlar:

200 OK — İstek başarılı, işte cevabın. Bir veri getirdiğinde en sık dönersin.

201 Created — Yeni bir kaynak oluşturuldu. Özellikle POST isteklerinden sonra doğru olan budur.

204 No Content — İşlem başarılı ama dönecek bir veri yok. Silme işlemlerinden sonra sık kullanılır.

400 Bad Request — İstemcinin gönderdiği veride bir sorun var. Eksik alan, yanlış format gibi.

404 Not Found — Aranan kaynak yok. Var olmayan bir id istendiğinde döndürülür.

500 Internal Server Error — Sunucu tarafında beklenmeyen bir hata oluştu. Bunu genelde sen elle dönmezsin; bir yeri patladığında .NET otomatik döner.

ControllerBase'in Sunduğu Yardımcılar

İyi haber şu: bu kodları elle ayarlaman gerekmiyor. ControllerBase sınıfından miras aldığımız için, her durum kodu için okunması kolay bir yardımcı metot elimizin altında. Küçük bir örnekle görelim; bir kullanıcıyı id'sine göre getiren, bulamazsa düzgün cevap dönen bir metot:

[HttpGet("{id}")]
public IActionResult GetById(int id)
{
    if (id <= 0)
    {
        return BadRequest("Geçersiz id değeri.");
    }

    var user = _users.FirstOrDefault(u => u.Id == id);

    if (user is null)
    {
        return NotFound();
    }

    return Ok(user);
}

Bu metot üç farklı yol izleyebiliyor. id geçersizse 400, kullanıcı yoksa 404, her şey yolundaysa veriyle birlikte 200 dönüyor. Dikkat edersen kodun kendisi neredeyse cümle gibi okunuyor: "id sıfırdan küçükse kötü istek dön, kullanıcı bulunamazsa yok dön, yoksa tamam de." İşte doğru durum kodları, kodu bu kadar okunabilir kılıyor.

201 Created'ı Doğru Dönmek

Yeni bir kaynak oluşturduğunda sadece 201 dönmek yetmez; iyi bir API, oluşturulan kaynağın nerede bulunacağını da söyler. Bunun için CreatedAtAction yardımcısı var. Yeni bir kullanıcı ekleyen bir metotta şöyle görünür:

[HttpPost]
public IActionResult Create(User newUser)
{
    _users.Add(newUser);

    return CreatedAtAction(
        nameof(GetById),
        new { id = newUser.Id },
        newUser);
}

Burada üç şey oluyor. Durum kodu 201 olarak