Durum kodu ilk cümledir
HTTP durum kodu, yanıtın genel sonucunu anlatır. Başarı, yönlendirme, istemci hatası ve sunucu hatası farklı sınıflardır. Örneğin 201 yeni bir kaynağın oluştuğunu; 202 isteğin kabul edildiğini fakat işlemenin henüz tamamlanmadığını bildirir. Bunları aynı “işlem tamam” mesajına çevirmek, kullanıcının beklentisini bozabilir.
Bir video yükleme ekranı düşünün. Dosya sunucuya ulaştığında kullanıcıya “Video yayında” demek yerine “Video işleniyor” demek gerekebilir. Arayüzdeki küçük bir ifade, arka plandaki işin gerçek durumuna dayanmalıdır.
Durum kodlarının anlamları: MDN HTTP durum kodları.
Hata yanıtı da bir sözleşmedir
RFC 9457, HTTP API hatalarını makine tarafından okunabilir bir biçimde anlatmak için Problem Details yapısını tanımlar. JSON karşılığı application/problem+json türünü kullanır. type, title, status ve detail gibi alanlar, problemin türünü ve açıklamasını taşımaya yardımcı olur.
Aşağıdaki sade örnekte sunucu gerçek HTTP durumunu da 422 olarak gönderir. about:blank, ayrıca tanımlanmış özel bir problem türü olmadığını belirtir. Örnek, bütün API’ler için tek zorunlu şablon değildir.
{
"type": "about:blank",
"title": "Unprocessable Content",
"status": 422,
"detail": "E-posta alanı geçerli bir adres içermeli."
}Biçim ve alan tanımları: RFC 9457.
Yanıtı bir sonraki adıma çevir
“Bir hata oluştu” mesajı tek başına pek yardımcı olmaz. Bir iletişim formunda e-posta alanı hatalıysa kullanıcıya hangi alanı düzeltmesi gerektiği gösterilebilir. Bağlantı kesildiyse, yazdığı metni kaybetmeden yeniden deneme olanağı sunulabilir.
Burada amaç bütün teknik ayrıntıları ekrana taşımak değildir. Kullanıcının işini tamamlamasını sağlayacak bilgi ile geliştirme ekibinin teşhis için ihtiyaç duyduğu bilgiyi ayrı ele almaktır. Sunucu içi yollar, erişim anahtarları veya ham hata yığınları son kullanıcı yanıtına eklenmemelidir.
Ekip için ortak bir dil kur
Yeni bir uç nokta tasarlarken başarılı örnek kadar başarısız örnekleri de yazın. Eksik alan, bulunamayan kaynak, yetkisiz işlem ve geçici servis sorunu karşısında arayüzün ne göstereceğini birlikte belirleyin.
Bir sözleşme, yalnızca alan adlarını listeleyen belge değildir. Kullanıcı beklerken ne göreceğini, ne zaman tekrar deneyebileceğini ve hangi durumda işlem yapmayı bırakacağını da netleştirir. İyi hata tasarımı, teknik ayrıntıyla insan deneyimi arasında kurulan bu bağlantıda ortaya çıkar.