REST Api Hata Yönetimi

Bu yazı RESTFul Api Tasarım İncelikleri serisinin bir parçası niteliğindedir. Eğer okumadıysanız önce serinin diğer yazılarını okumanızı tavsiye ederim.

Hatayla karşılaşmaktan daha da kötüsü “ne olduğu belirsiz” bir hatayla karşılaşmak. REST API’niz kullananlara saç baş yoldurmasın istiyorsanız, hataları ve nedenlerini net olarak açıklayın. Bunu yaparken HTTP durum kodlarını da kullanmayı ihmal etmeyin. Standart HTTP durum kodları neredeyse her hatanın genel tanımı için yeterli olacaktır. Bu kodla beraber güzel bir açıklama yaparsanız tadından yenmez.

HTTP durum kodunu cevabın başlık kısmı ile gönderebilirsiniz. İstemci kodlayanın işini daha da kolaylaştırmak isterseniz kodu sadece HTTP başlığında değil içerikte de verebilirsiniz.

JSON formatında örnek bir hata mesajı şöyle formüle edilebilir;

{
 "status": 429,
 "message": "Çok fazla istek gönderildi"
 "code": 10200,
 "info": "http:\/\/www.evrenbal.com\/api\/v1\/errors\/10200"
}

Bu cevaptaki “status” standart HTTP kodlarından biri, “message” human-readable olarak tabir edilen, bir insanın okuyunca fikir sahibi olacağı mesajı, “code” hata kodunu, “info”: Bu hata koduyla ilgili eksra bilgi bulunabilecek örneğin yardım dökümanını içerebilir. Bu yapı sadece bir örnek ve ihtiyacınıza göre başka şekillerde de formülüze edilebilir.

Örneğin;

{
"status": 500,
"message": "Bir sunucu hatası oluştu",
"description": "Sunucu hatasının 3 sayfa uzunluğundaki detayı;"
"code": 10201,
"info": "http:\/\/www.evrenbal.com\/api\/v1\/errors\/10201"
}

{
"status": 422,
"message": "İstek İşlenemedi",
"errors": [
  { "code": 20501,
    "field" : "kullanici_adi",
    "message: "Kullanıcı adı en az 5 karakterden oluşmalıdır.
    "info": "http:\/\/www.evrenbal.com\/api\/v1\/errors\/20501"
  },
  {
   "code": 20601,
   "field": "sifre",
   "message": "Şifre en az 8 karakterde oluşm alıdır."
   "info": "http:\/\/www.evrenbal.com\/api\/v1\/errors\/20601"
  }
] 
}

HTTP Durum Kodları

Rest API uygulamalarında sıklıkla ihtiyaç duyulan HTTP statü kodları ve açıklamalarını aşağıda paylaşıyorum;

200 OK – Başarılı bir GET, PUT, PATCH veya DELETE işleminden sonra döndürülen statü kodudur. Eğer kayıt oluşturmak için gönderilmediyse (ki genelde öyle olmalıdır) POST içinde kullanılabilir.
201 Created- Bir oluşturma işlemi için yapılan bir POST isteğine döndürülen başarılı yanıtlarda kullanılan durum kodudur.
204 No Content Bir içerik döndürmesine gerek olmayan başarılı bir yanıt için kullanılabilir. Örneği bir DELETE isteği başarılı sonuçlandıysa ve geriye bir mesaj döndürülmesine gerek yoksa kullanabilirsiniz.
400 Bad Request – Yapılan istekle ilgili bir sorun varsa, örneğin gönderilmesi gereken parametreler gönderilmemişse bu kodu kullanabilirsiniz.
401 Unauthorized – Yanlış kullanıcı tanımlama bilgileri veya hiç bilgi gönderilmediyse kullanabilirsiniz.
403 Forbidden – Çoğunlukla 401’le karıştırılan/yerine geçen kullanıcının tanınmadığı değil, yetkisinin olmadığı durumlarda kullanılan hata kodudur.
404 Not Found – Neredeyse en çok bilinen hata kodu. İstenen kaynak sunucuda bulunmuyorsa bu kod döndürülür.
405 Method Not Allowed – İstek gönderilirken kullanılan method giriş yapan kullanıcı için desteklenmiyorsa kullanılır.
422 Unprocessable Entity – Doğrulama gerektiren durumlarda doğrulama yapılamıyorsa (Örneğin kullanıcı adı en az 8 karakter olmalı hatasını döndüreceksek) kullanılır.
429 Too Many Request – Rate limit – İstek sınırı aşıldıysa bunu belirtmek için kullanılır.
500 Internal Server Error – Çoğu zaman bu hata kontrolümüz dışında gerçekleşir, ama bunu da handle edecek alt seviyede bir hata yönetim yapısı kurarsak hem kullanıcıya göstermemiz, hem düzgün log tutabilmemiz açısından faydalı olur.

Kayıt Tutma – Log

Yazıyı ilk kurgularken aklıma gelmeyen ama önemli bir başlık da kayıt tutma, yani loglama. Aslına bakarsanız loglama sadece hata kaydı için değil, uygulamanızın yapısına göre yapılan işlem -transaction- kayıtları için de tutulabilir ama en temel olarak hata kayıtlarını tutmanız işinizi çok kolaylaştırır. Geliştirici olarak her ne kadar test yapsak da, API’mizi vahşi hayata bıraktığımızda kullanıcılar bambaşka fantastik hatalarla karşılaşabilirler. Çoğu zaman bize bunun dönüşü bile yapılmaz, ama yapılsa bile durumu anlamamız veya hatayı tekrar etmemiz kolay olmaz. Bunun için kayıt tutuyor olmamız çok önemli.

Loglama konusu başlı başlına bir konu ve burada detayına girmeyi düşünüyorum. Önümüzdeki günlerde PHP Monogolog kütüphanesi ile ilgili bir yazı yazmayı düşünüyorum, bu yazı içerisinde loglama prensiplerinden de genel hatları ile bahsedeceğim.

Benim En Sık Yaptığım Hata – Hata yönetimini yönetemediğim yer 🙂

Benim kişisel olarak en çok yaptığım hata, API tarafında hata kodlarını düzgün yayınlarken, istemci tarafında bunları kullanmamak oluyor. İstemci’den beklediğim tepkiyi alamayınca, API’nin döndürdüğü cevaba bakıp hata kodunu görebiliyorum ama istemcide bunu kullanmadığım (handling) için bir anlamı olmuyor. Yani hata yönetimi tek taraflı değil, iki taraflı uygulanması gereken bir zorunluluk.

Bundan sonraki bölüm olan “Güvenlik” başlığında görüşmek üzere…