REST API Tasarımında Doğru HTTP Durum Kodları

REST API Tasarımında Doğru HTTP Durum Kodları, Web Geliştirme alanında sıkça karşılaşılan ve doğru uygulandığında fark yaratan konulardan biri. Bu yazı konuyu 5 temel noktada ele alıyor, çalışan bir PHP örneği üzerinden ilerliyor, sonunda da uygulamada nelere dikkat edilmesi gerektiğini özetliyor.

REST API Tasarımında Doğru HTTP Durum Kodları nedir, neden önemlidir?

Her yanıtı 200 ile döndürüp hatayı gövdedeki bir alanla bildirmek, API'yi kullanan uygulamaların hata yönetimini zorlaştırır. HTTP durum kodları, istemcinin "tekrar deneyeyim mi, kullanıcıya mı göstereyim, oturumu mu yenileyeyim" kararını gövdeyi okumadan vermesini sağlar.

Kritik noktalar

• 2xx başarı: 200 genel başarı, 201 yeni kayıt oluşturuldu, 204 gövdesiz başarı.
• 4xx istemci hatası: 400 bozuk istek, 401 kimlik yok, 403 yetki yok, 404 bulunamadı, 422 doğrulama hatası, 429 hız sınırı.
• 5xx sunucu hatası: 500 beklenmeyen hata, 502/503 bağımlı servis yanıt vermiyor; istemci tekrar deneyebilir.
• Makine okunur kod: Durum kodunun yanında sabit bir hata kodu (dogrulama, yetki_yok) istemcinin dalını belirler.
• Tutarlı gövde: Başarılı ve hatalı yanıtlar aynı iskeleti (ok, kod, hata) izlemelidir.

Uygulamalı örnek

Teoriyi somutlaştırmak için kısa bir PHP örneğine bakalım:

function json_yanit(int $durum, array $veri): never
{
    http_response_code($durum);
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode($veri, JSON_UNESCAPED_UNICODE);
    exit;
}

if (!$uye) json_yanit(401, ['ok' => false, 'kod' => 'oturum_yok', 'hata' => 'Giriş yapın.']);
if (!$yetkili) json_yanit(403, ['ok' => false, 'kod' => 'yetki_yok', 'hata' => 'Bu işlem için yetkiniz yok.']);
if (!$urun) json_yanit(404, ['ok' => false, 'kod' => 'bulunamadi', 'hata' => 'Ürün bulunamadı.']);
if ($hatalar) json_yanit(422, ['ok' => false, 'kod' => 'dogrulama', 'hatalar' => $hatalar]);
json_yanit(201, ['ok' => true, 'id' => $yeniId]);

Örneği kendi projenize uyarlarken değişken adlarını ve yapılandırma değerlerini ortamınıza göre değiştirmeyi unutmayın.

Neden önemli? Kazanımlar

Bu yaklaşımı benimsediğinizde elde edeceğiniz başlıca faydalar:

• Bakımı kolay ve okunur bir kod tabanı sağlar
• Farklı cihaz ve tarayıcılarda tutarlı sonuç verir
• Ekip içinde ortak bir uygulama standardı oluşturur
• Sayfa performansını ve kullanıcı deneyimini iyileştirir

Sonuç

REST API Tasarımında Doğru HTTP Durum Kodları, küçük ama düzenli adımlarla ustalaşılan konulardan biri. Özellikle 2xx başarı ve Tutarlı gövde başlıklarını uygulamaya geçirmek iyi bir başlangıç olur.

İlgili içerikler:

• MySQL İndeksleri ile Sorgu Hızlandırma
• JavaScript Fetch API ve async/await ile Veri Çekme
• Tailwind CSS ile Titreşimsiz Dark Mode

Daha fazla uygulamalı içerik için Akademi derslerine ve blog yazılarına göz atabilirsiniz.