REST API'lerde Hata Yönetimi: En İyi Uygulamalar ve Standart Hata Yanıtları

REST API'lerde hata yönetimi, tutarlı hata formatları ve uygun HTTP durum kodları ile yapılır. Bu yaklaşım, istemcilerin hataları anlamasını ve uygun şekilde tepki vermesini sağlar. Doğru bir hata yönetimi stratejisi, API'nizin güvenilirliğini ve kullanılabilirliğini doğrudan etkiler.

Hata Yönetimi Neden Önemlidir?

API tüketicileri, hata durumunda neyin yanlış gittiğini ve nasıl düzeltebileceklerini bilmek ister. Standartlaştırılmamış hata yanıtları, istemci tarafında kafa karışıklığına ve hataların yanlış işlenmesine yol açar. Bu nedenle, tutarlı bir hata formatı ve doğru durum kodları kullanmak, API'nizin kalitesini artırır. Örneğin, Bubble ile API entegrasyonu sırasında hata yanıtlarını doğru işlemek, uygulamanın beklendiği gibi çalışması için kritiktir.

Standart Hata Yanıtı Formatı Nasıl Olmalı?

Yaygın olarak kullanılan bir hata formatı, RFC 7807 (Problem Details for HTTP APIs) standardına dayanır. Bu formatta hata yanıtı şu alanları içerir:

• type: Hata türünü belirten URI
• title: Hatayı özetleyen kısa bir başlık
• status: HTTP durum kodu
• detail: Hatanın detaylı açıklaması
• instance: Hatanın oluştuğu özel kaynak (isteğe bağlı)

Örnek JSON yanıtı:

{
  "type": "https://example.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'email' field must be a valid email address.",
  "instance": "/api/users"
}

Bu formatı kullanarak tüm hata yanıtlarınızı standartlaştırabilir ve istemcilerin hataları programatik olarak işlemesini kolaylaştırabilirsiniz.

HTTP Durum Kodlarını Doğru Kullanma

Her hata için uygun HTTP durum kodunu seçmek önemlidir. Aşağıdaki tabloda sık kullanılan durum kodları ve anlamları listelenmiştir:

Doğru durum kodunu kullanmak, istemcinin hatayı doğru şekilde ele almasını sağlar. Örneğin, bir kaynak bulunamadığında 404 dönmek, istemcinin kullanıcıya uygun bir mesaj göstermesine olanak tanır.

Hata Yanıtında Hangi Bilgiler Olmalı?

Hata yanıtı, istemcinin hatayı anlaması ve çözmesi için yeterli bilgiyi içermelidir. İşte dikkat edilmesi gerekenler:

• Hata türü ve başlık: Hatayı kategorize eder, istemci genel bir işlem yapabilir.
• Detaylı açıklama: İnsan tarafından okunabilir, hatanın nedenini belirtir.
• Hata kodu: İstemcinin belirli bir hatayı tanımlaması için benzersiz bir kod (opsiyonel).
• Hata kaynağı: Hangi alan veya parametrenin hataya yol açtığını belirtmek (özellikle doğrulama hatalarında).
• İzleme ID'si: Sunucu tarafında hata ayıklama için bir ID (isteğe bağlı).

Örneğin, birden fazla doğrulama hatası içeren bir yanıt şöyle olabilir:

{
  "type": "https://example.com/errors/validation-error",
  "title": "Multiple Validation Errors",
  "status": 422,
  "errors": [
    {
      "field": "email",
      "message": "Email formatı geçersiz"
    },
    {
      "field": "password",
      "message": "Şifre en az 8 karakter olmalı"
    }
  ]
}

Sık Yapılan Hatalar ve Kaçınılması Gerekenler

Hata yönetiminde aşağıdaki hatalardan kaçınmalısınız:

• Güvenlik hassas bilgilerini ifşa etmek: Stack trace veya veritabanı detaylarını asla hata yanıtına eklemeyin. Bu bilgileri yalnızca sunucu loglarına yazın.
• Tüm hatalara aynı durum kodunu kullanmak: Her hata türüne uygun kod seçin; örneğin, doğrulama hatası için 400 değil 422 kullanın.
• Aşırı genel hata mesajları: "Bir hata oluştu" gibi mesajlar yerine, hatayı açıklayan net bilgiler verin.
• Tutarsız hata formatı: Tüm hata yanıtlarında aynı yapıyı kullanın. Karışık formatlar istemci geliştirmeyi zorlaştırır.
• Hata yönetimini ihmal etmek: Özellikle no-code araçlarında, Bubble ile API entegrasyonu gibi durumlarda hataların doğru yönetilmemesi uygulama kararlılığını etkileyebilir.

Örnek Uygulama: Express.js ile Hata Middleware'i

Aşağıda Express.js'de merkezi bir hata middleware'i örneği verilmiştir. Bu middleware, tüm hataları yakalar ve standart formatta yanıt döner:

// Hata middleware'i
app.use((err, req, res, next) => {
  const status = err.status || 500;
  const response = {
    type: "https://example.com/errors/" + (err.code || "internal-error"),
    title: err.title || "Internal Server Error",
    status: status,
    detail: err.message || "An unexpected error occurred.",
    instance: req.originalUrl
  };
  res.status(status).json(response);
});

Bu yapı, hataları merkezi bir noktadan yönetmenizi sağlar ve tüm uygulama genelinde tutarlılık sunar. Özel hata sınıfları oluşturarak (örneğin ValidationError, NotFoundError) farklı durumlar için özelleştirilmiş yanıtlar üretebilirsiniz.

Frontend tarafında hata yönetimini kolaylaştıran kütüphaneler de mevcuttur. Örneğin, React Query vs SWR gibi araçlar, API hatalarını otomatik olarak yönetmeye yardımcı olur ve hata durumlarını istemci tarafında kolayca ele almanızı sağlar.

Sonuç olarak, REST API'lerde hata yönetimi, standart bir hata formatı, doğru durum kodları ve yeterli bilgi içeren yanıtlarla sağlanır. Bu en iyi uygulamaları takip ederek API'nizin kullanıcı deneyimini ve güvenilirliğini artırabilirsiniz.

Sık Sorulan Sorular

REST API'lerde hata yönetimi neden önemlidir?

Hata yönetimi, istemcilerin hataları doğru anlamasını ve uygun şekilde tepki vermesini sağlar. Standartlaştırılmış hata yanıtları, API kullanılabilirliğini ve geliştirici deneyimini iyileştirir.

Standart bir hata yanıtı formatı nasıl olmalıdır?

RFC 7807 standardı, hata yanıtında type, title, status, detail ve instance alanlarını önerir. Bu format, hataların programatik olarak işlenmesini kolaylaştırır.

Hangi HTTP durum kodları hangi hatalar için kullanılmalıdır?

400 Bad Request (geçersiz istek), 401 Unauthorized (kimlik doğrulama hatası), 403 Forbidden (yetki hatası), 404 Not Found (kaynak bulunamadı), 422 Unprocessable Entity (doğrulama hatası) ve 500 Internal Server Error (sunucu hatası) yaygın olarak kullanılır.

Hata yanıtında hangi bilgiler bulunmalıdır?

Hata türü, açıklayıcı mesaj, durum kodu, hata kodu ve varsa hataya neden olan alan gibi bilgiler bulunmalıdır. Güvenlik hassas bilgileri (stack trace gibi) asla yanıta eklenmemelidir.