HTTP Durum Kodları Nedir ve Neden Hayati Öneme Sahiptir?

API geliştirme sürecinde, istemci ile sunucu arasındaki iletişimin temelini oluşturan HTTP durum kodları, sistemlerinizin sağlıklı çalışmasını sağlamanın yanı sıra hata ayıklama ve kullanıcı deneyimi açısından kritik bir rol oynar. Bu kodlar, her bir isteğin sonucunu standartlaştırılmış bir şekilde ileterek, API’lerinizin hem anlaşılır hem de bakımı kolay olmasını sağlar.

API’ler, modern yazılım mimarilerinin bel kemiğini oluşturur ve uygulamalar arası veri alışverişini mümkün kılar. Bu alışverişin temelinde ise HTTP (Hypertext Transfer Protocol) yatar. HTTP, istemcilerin (tarayıcılar, mobil uygulamalar veya diğer servisler) sunuculara (API’niz) istek göndermesi ve sunucuların bu isteklere yanıt vermesi üzerine kurulu bir protokoldür. İşte bu yanıtların önemli bir parçası da HTTP durum kodlarıdır. Peki, bu üç haneli sayılar tam olarak ne anlama gelir ve API geliştirme sürecinde neden bu kadar kilit bir role sahiptir?

Her bir HTTP durum kodu, sunucunun bir isteği başarıyla işleyip işleyemediğini veya işlem sırasında ne tür bir sorunla karşılaştığını gösteren standart bir mesajdır. Bu kodlar, genellikle üç basamaklı sayılardan oluşur ve ilk basamak, yanıtın genel kategorisini belirtir. Bu kategoriler, 1xx’den 5xx’e kadar uzanır ve her biri farklı bir anlama gelir:

* 1xx (Bilgilendirici Yanıtlar): İstek alındı ve işlem devam ediyor. Nadiren doğrudan API yanıtlarında kullanılır.
* 2xx (Başarılı Yanıtlar): İstek başarıyla alındı, anlaşıldı ve kabul edildi.
* 3xx (Yönlendirme Yanıtları): İstek tamamlanmak için ek eylem gerektiriyor. Kaynak taşınmış olabilir.
* 4xx (İstemci Hataları): İstek geçersiz sözdizimi nedeniyle sunucu tarafından anlaşılamadı veya işlenemedi. Genellikle istemcinin hatasıdır.
* 5xx (Sunucu Hataları): Sunucu, geçerli bir isteği yerine getiremedi. Sorun sunucu tarafındadır.

Bu kodlar, API geliştiricileri için sadece hata ayıklama aracı olmaktan öte, aynı zamanda iyi bir API tasarımının ve kullanıcı deneyiminin temelini oluşturur. Örneğin, bir kullanıcının mobil uygulaması sunucuya bir veri gönderme isteği yaptığında, 201 Created kodu, verinin başarıyla kaydedildiğini bildirirken, 400 Bad Request kodu, gönderilen veride bir hata olduğunu ve istemcinin isteği düzeltmesi gerektiğini belirtir. Bu sayede, istemci tarafı aldığı yanıtı kolayca anlayabilir ve buna göre aksiyon alabilir. Bu durum, özellikle karmaşık ve dağıtık sistemlerde, farklı servislerin birbiriyle tutarlı bir şekilde iletişim kurabilmesi için vazgeçilmezdir.

Ayrıca, durum kodlarının doğru kullanımı, API’lerinizin daha güvenilir ve bakımı daha kolay olmasını sağlar. Geliştiriciler, bir hata kodu gördüklerinde, sorunun kaynağını hızla tespit edebilirler. Sunucu hataları (5xx) genellikle altyapı veya kod sorunlarına işaret ederken, istemci hataları (4xx) genellikle API kullanımında veya girdi verilerinde bir sorun olduğunu gösterir. Böylece, sorunların kategorize edilmesi ve çözüme yönelik adımların atılması çok daha verimli hale gelir.

Dolayısıyla, API geliştirme yolculuğunuzda, HTTP durum kodlarına hakim olmak, sadece “işleyen” bir API değil, aynı zamanda “sağlam”, “anlaşılır” ve “bakımı kolay” bir API oluşturmanız için temel bir adımdır. Bu kodlar, API’nizin kullanıcılarıyla ve diğer servislerle kurduğu sessiz ama etkili bir iletişim dilidir. Bu dili doğru kullanmak, geliştirdiğiniz sistemlerin genel kalitesini doğrudan etkileyecektir.

Başarılı Yanıtlar (2xx): İstekleriniz Sorunsuz Çalışıyor mu?

API geliştirme sürecinde en çok görmeyi arzuladığımız yanıtlar şüphesiz 2xx sınıfına ait olanlardır. Bu durum kodları, bir istemcinin gönderdiği isteğin sunucu tarafından başarıyla alındığını, anlaşıldığını ve amacına ulaştığını gösterir. Doğru 2xx kodu seçimi, API’nizin davranışını açıkça belirtir ve istemcilerin sonraki adımları doğru bir şekilde atmasına yardımcı olur. Gelin, en sık kullanılan başarılı yanıt kodlarını ve kullanım senaryolarını inceleyelim.

200 OK: Her Şey Yolunda mı?

200 OK, HTTP’nin en bilinen ve en yaygın başarılı yanıtıdır. Bir GET, PUT, POST veya DELETE isteğinin başarıyla tamamlandığını ve beklenen bir yanıt gövdesinin (body) döndürüldüğünü belirtir. Özellikle bir kaynaktan bilgi almak (GET) veya bir kaynağı güncellemek (PUT/PATCH) gibi işlemlerden sonra bu kodu sıkça görürüz.

Kullanım Senaryosu: Bir e-ticaret uygulamasında, kullanıcıların sepetlerindeki ürünleri listelemek için bir API isteği gönderdiğini düşünelim.

// İstemci tarafı (Örnek JavaScript kodu)
fetch('/api/sepetim')
  .then(response => {
    if (response.status === 200) {
      return response.json();
    }
    // Hata durumu, örneğin 404 eğer sepet bulunamazsa
    throw new Error('Sepet getirilirken bir sorun oluştu.');
  })
  .then(data => {
    console.log('Sepet içeriği:', data);
    // Sepeti kullanıcı arayüzünde göster
  })
  .catch(error => {
    console.error('Hata:', error);
  });

Bu örnekte, response.status === 200 kontrolü, sepet içeriğinin başarıyla alındığını ve istemcinin bu veriyi güvenle kullanabileceğini gösterir.

201 Created: Yeni Bir Kaynak Oluşturuldu mu?

201 Created, bir POST isteğinin başarıyla sonuçlandığını ve sunucuda yeni bir kaynak oluşturulduğunu belirtir. Bu yanıt, genellikle oluşturulan kaynağın URL'sini içeren bir Location başlığı ve kaynağın kendisini içeren bir yanıt gövdesi ile birlikte gelir. Bu, istemcinin yeni kaynağa hemen erişebilmesini sağlar.

Vaka Analizi: E-ticaret Uygulamasında Sipariş Oluşturma

Bir kullanıcının, sepetindeki ürünleri kullanarak yeni bir sipariş oluşturduğunu varsayalım. İstemci, API'ye bir POST isteği gönderir:

// İstemci tarafı
const siparisData = {
  urunler: [{ id: 1, adet: 2 }, { id: 3, adet: 1 }],
  adres: "İstanbul, Türkiye"
};

fetch('/api/siparisler', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(siparisData)
})
.then(response => {
  if (response.status === 201) {
    const locationHeader = response.headers.get('Location');
    console.log('Yeni sipariş başarıyla oluşturuldu. Konum:', locationHeader);
    return response.json();
  }
  throw new Error('Sipariş oluşturulurken bir sorun oluştu.');
})
.then(data => {
  console.log('Oluşturulan sipariş detayı:', data);
  // Kullanıcıyı yeni sipariş sayfasına yönlendir
  // window.location.href = data.url; // Location başlığı yerine yanıttaki URL kullanılabilir
})
.catch(error => {
  console.error('Hata:', error);
});

Bu durumda, sunucu başarılı bir 201 yanıtı döndürerek hem siparişin başarıyla kaydedildiğini onaylar hem de yeni siparişin detaylarına nasıl erişileceğini (genellikle Location başlığında veya yanıt gövdesinde bir URL ile) belirtir.

204 No Content: Yanıt Gövdesine Gerek Yok mu?

204 No Content, bir isteğin başarıyla işlendiğini ancak sunucunun yanıt olarak herhangi bir içerik döndürmesine gerek olmadığını belirtir. Özellikle DELETE istekleri veya bir kaynağın başarılı bir şekilde güncellendiği (ancak güncelleme sonrası kaynağın kendisinin döndürülmesine gerek olmadığı) senaryolarda kullanılır. Bu, ağ trafiğini azaltmaya yardımcı olur.

Kullanım Senaryosu: Bir kullanıcının blog gönderisini sildiği bir API düşünelim.

// İstemci tarafı
const postId = 123;
fetch(/api/gonderiler/${postId}, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer ' + token
  }
})
.then(response => {
  if (response.status === 204) {
    console.log(Gönderi #${postId} başarıyla silindi.);
    // Kullanıcı arayüzünden gönderiyi kaldır
  } else if (response.status === 404) {
    console.warn(Gönderi #${postId} bulunamadı.);
  } else {
    throw new Error('Gönderi silinirken bir sorun oluştu.');
  }
})
.catch(error => {
  console.error('Hata:', error);
});

Burada 204 yanıtı, gönderinin başarıyla silindiğini ancak sunucunun silinen kaynağın herhangi bir detayını veya onay mesajını göndermeye gerek duymadığını gösterir.

Başarılı yanıt kodlarının doğru ve tutarlı kullanımı, API'nizin tahmin edilebilirliğini artırır ve hem API'yi tüketen geliştiricilerin hem de son kullanıcıların daha sorunsuz bir deneyim yaşamasını sağlar. Her başarılı işlemin sonunda doğru 2xx kodunu döndürmek, API tasarımının temel taşlarından biridir.

Yönlendirme Yanıtları (3xx): Kullanıcıyı veya İstemciyi Doğru Yere Nasıl Yönlendirmeliyiz?

HTTP durum kodlarının 3xx sınıfı, istemcinin isteğini tamamlamak için ek bir eylem gerçekleştirmesi gerektiğini belirtir. Bu genellikle, istenen kaynağın farklı bir URL'ye taşındığı veya isteğin başka bir kaynağa yönlendirilmesi gerektiği durumlarda ortaya çıkar. Yönlendirmeler, API sürüm yükseltmeleri, kalıcı URL değişiklikleri veya yük dengeleme gibi senaryolarda kritik bir rol oynar. Doğru 3xx kodunun kullanılması, hem istemci davranışını optimize eder hem de arama motoru optimizasyonu (SEO) açısından önem taşır.

301 Moved Permanently: Kalıcı Olarak Taşındı mı?

301 Moved Permanently, istenen kaynağın kalıcı olarak yeni bir URL'ye taşındığını ve gelecekteki tüm isteklerin bu yeni URL'ye yapılması gerektiğini belirtir. Bu yanıt, Location başlığında yeni URL'yi içerir. Tarayıcılar ve bazı API istemcileri, bu yönlendirmeyi otomatik olarak önbelleğe alır ve sonraki istekleri doğrudan yeni URL'ye yapar.

Kullanım Senaryosu: Bir API'nin eski bir uç noktasını yeni bir yapıya taşıdığınızı düşünelim. Örneğin, /api/v1/urunler uç noktasını /api/urunler olarak değiştirdiniz.

HTTP/1.1 301 Moved Permanently
Location: https://api.example.com/api/urunler

Bu durumda, eski uç noktaya yapılan her istek, otomatik olarak yeni uç noktaya yönlendirilir. Bu, hem eski entegrasyonların kırılmamasını sağlar hem de istemcilere güncel URL'yi bildirir. Özellikle halka açık API'lerde veya web sitelerinde, SEO değeri taşıyan URL'lerin kalıcı olarak taşınması gerektiğinde 301 kullanımı olmazsa olmazdır.

302 Found (Geçici) veya 303 See Other (POST Sonrası Yönlendirme): Geçici Bir Yönlendirme mi?

* 302 Found: İstek tamamlanana kadar kaynağın geçici olarak başka bir adreste bulunduğunu belirtir. İstemciler, gelecekteki istekler için orijinal URL'yi kullanmaya devam etmelidir. Bu, genellikle bir kaynağın geçici olarak bakıma alınması veya sunucu tarafında geçici bir yönlendirme gerektiğinde kullanılır. Ancak, bazı eski istemciler 302'yi yanlışlıkla 303 gibi davranabilir, bu da POST istekleri sonrası GET yönlendirmelerinde sorunlara yol açabilir.
* 303 See Other: Özellikle bir POST isteğinin başarıyla işlenmesinden sonra, istemciyi farklı bir kaynağa (genellikle bir GET isteği ile erişilebilecek bir onay veya sonuç sayfasına) yönlendirmek için kullanılır. Bu, tarayıcının "yenile" düğmesine basıldığında POST isteğinin tekrar gönderilmesini önler (PRG – Post/Redirect/Get deseni).

Kullanım Senaryosu: Form Gönderimi Sonrası Onay Sayfasına Yönlendirme

Bir kullanıcı bir form doldurup gönderdiğinde, sunucu veriyi işledikten sonra kullanıcıyı bir onay sayfasına yönlendirmek isteyebilir.

// Sunucu tarafı (Örnek Node.js / Express kodu)
app.post('/api/kayit', (req, res) => {
  // Veritabanına kaydetme işlemi
  const yeniKullaniciId = veritabaninaKaydet(req.body);
  // Kayıt başarılı oldu, kullanıcıyı onay sayfasına yönlendir
  res.redirect(303, /kayit-basarili?id=${yeniKullaniciId});
});

Bu örnekte, res.redirect(303, ...) ile kullanıcı, kayıt işleminin başarılı olduğunu gösteren bir GET isteği ile /kayit-basarili URL'sine yönlendirilir. Bu, kullanıcı deneyimi açısından daha temiz ve güvenlidir.

307 Temporary Redirect ve 308 Permanent Redirect: Metot Güvenliği ile Yönlendirme

* 307 Temporary Redirect: 302'ye benzer şekilde geçici bir yönlendirmedir, ancak istemcinin orijinal isteğin HTTP metodunu (GET, POST vb.) korumasını garanti eder. Yani, bir POST isteği 307 yanıtı alırsa, istemci yeni URL'ye de bir POST isteği gönderir. 302'de ise istemci bazen POST'u GET'e çevirebilirdi.
* 308 Permanent Redirect: 301'e benzer şekilde kalıcı bir yönlendirmedir, ancak yine metot güvenliğini garanti eder. Orijinal isteğin metodu ne olursa olsun, yeni URL'ye aynı metot ile istek yapılır.

Önemli Not: 301/302 genellikle tarayıcılar tarafından GET isteği olarak yeniden yapılır. Eğer orijinal isteğin metodunu korumak istiyorsanız (özellikle POST veya PUT gibi metotlar için), 307 veya 308 kullanmak daha güvenlidir. Ancak çoğu zaman API'lerde kalıcı yönlendirmeler için 301, geçici yönlendirmeler için 302 tercih edilir, özellikle de bu yönlendirmeler genellikle GET istekleriyle tetiklendiğinde veya istemci davranışının bilindiği durumlarda.

API'lerinizde yönlendirme kodlarını doğru kullanmak, kaynaklarınızın esnekliğini artırır, URL değişikliklerini yönetmeyi kolaylaştırır ve istemci entegrasyonlarının daha sağlam olmasını sağlar. Ancak, gereksiz yönlendirmelerden kaçınmak, API performansını olumlu yönde etkiler, zira her yönlendirme, istemci için ek bir HTTP isteği anlamına gelir.

İstemci Hataları (4xx): Kullanıcı Nerede Yanlış Yaptı?

4xx sınıfı durum kodları, API geliştirme sürecinde belki de en sık karşılaşılan ve doğru yönetilmesi gereken hataları temsil eder. Bu kodlar, istemcinin (API'nizi kullanan uygulama) isteğinde bir sorun olduğunu, yani sunucunun isteği işleyemediğini veya reddettiğini gösterir. Bu hataları doğru bir şekilde döndürmek, API'nizin kullanıcı dostu olmasını, hata ayıklama sürecini hızlandırmasını ve istemci uygulamalarının daha akıllı kararlar almasını sağlar.

400 Bad Request: İstek Geçersiz mi?

400 Bad Request, istemcinin sunucuya gönderdiği isteğin genel olarak geçersiz olduğunu belirtir. Bu, isteğin sözdizimsel olarak hatalı olduğu, eksik veya yanlış parametreler içerdiği veya başlıkların hatalı olduğu durumlarda kullanılır. Bu, genellikle istemcinin isteği düzeltmesi gerektiğini gösteren genel bir hatadır.

Kullanım Senaryosu: Bir kullanıcı kaydı API'sine e-posta formatı yanlış gönderildiğinde:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "status": 400,
  "code": "INVALID_EMAIL_FORMAT",
  "message": "Gönderilen e-posta adresi geçersiz formatta.",
  "details": [
    { "field": "email", "message": "Geçerli bir e-posta adresi girin." }
  ]
}

Bu yanıt, istemcinin tam olarak nerede hata yaptığını açıkça belirtir ve hatayı düzeltmesi için gerekli bilgiyi sağlar.

401 Unauthorized: Kimlik Doğrulama Başarısız mı?

401 Unauthorized, bir isteğin kimlik doğrulaması gerektirdiğini ancak istemcinin kimlik bilgilerini sağlamadığını veya sağladığı kimlik bilgilerinin geçersiz olduğunu belirtir. Genellikle bir WWW-Authenticate başlığı ile birlikte gelir, bu da istemciye hangi kimlik doğrulama yönteminin beklendiğini bildirir.

Vaka Analizi: Bankacılık Uygulamasında Hatalı Kimlik Doğrulama

Bir mobil bankacılık uygulamasının, kullanıcının hesap bakiyesini sorgulamak için bir API'ye istek gönderdiğini varsayalım. Eğer yetkilendirme token'ı eksik veya geçersizse:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="API Erişimi"
Content-Type: application/json

{
  "status": 401,
  "code": "AUTH_REQUIRED",
  "message": "Bu kaynağa erişim için kimlik doğrulama gereklidir."
}

İstemci bu yanıtı aldığında, kullanıcıdan tekrar giriş yapmasını isteyebilir veya geçerli bir token ile isteği yenileyebilir.

403 Forbidden: Yetkiniz Yok mu?

403 Forbidden, kimlik doğrulaması yapılmış olsa bile, istemcinin istenen kaynağa erişim iznine sahip olmadığını belirtir. Yani, istemcinin kim olduğu bilinir, ancak o eylemi gerçekleştirmeye veya o kaynağa erişmeye yetkili değildir.

Kullanım Senaryosu: Bir kullanıcının sadece kendi hesap bilgilerini görebildiği, ancak başka bir kullanıcının bilgilerine erişmeye çalıştığı durum:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "status": 403,
  "code": "PERMISSION_DENIED",
  "message": "Bu kaynağa erişim izniniz yok."
}

Bu, yetkilendirme (authorization) ile ilgili bir hatadır, kimlik doğrulama (authentication) ile değil.

404 Not Found: Kaynak Bulunamadı mı?

404 Not Found, sunucunun istenen kaynağı (URL) bulamadığını belirtir. Bu, en yaygın HTTP hatalarından biridir ve genellikle istemcinin yanlış bir URL'ye istek gönderdiğini gösterir.

Kullanım Senaryosu: Geçersiz bir ürün ID'si ile ürün detayı sorgulama:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "status": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "İstenen ürün bulunamadı."
}

Diğer Önemli 4xx Kodları:

* 405 Method Not Allowed: İstemcinin kullandığı HTTP metodu (GET, POST vb.) belirli bir kaynak için geçerli olmadığında döndürülür. Örneğin, sadece GET destekleyen bir uç noktaya POST isteği yapıldığında.
* 409 Conflict: Bir isteğin, kaynağın mevcut durumuyla çakıştığını belirtir. Örneğin, zaten var olan bir kullanıcı adıyla yeni bir kullanıcı oluşturmaya çalışıldığında.
* 429 Too Many Requests: İstemcinin belirli bir zaman diliminde çok fazla istek gönderdiğini (oran sınırlaması ihlali) belirtir. Genellikle bir Retry-After başlığı ile birlikte gelir.

API geliştirirken 4xx hatalarını doğru ve açıklayıcı bir şekilde döndürmek, API'nizin dış dünyaya karşı net bir arayüze sahip olmasını sağlar. Her bir hatanın nedenini ve nasıl düzeltileceğini açıklayan detaylı hata mesajları sunmak, entegrasyon sürecini büyük ölçüde kolaylaştırır.

Sunucu Hataları (5xx): Bizim Tarafımızda Neler Ters Gidiyor?

5xx sınıfı HTTP durum kodları, istemcinin isteği doğru olsa bile sunucunun isteği yerine getiremediği durumları işaret eder. Bu hatalar, genellikle sunucu tarafındaki bir problemden kaynaklanır; yani API'nizin kendisinde, veritabanında, entegre olduğu başka bir serviste veya sunucu altyapısında bir sorun var demektir. 5xx hatalarını anlamak ve yönetmek, API'nizin güvenilirliğini sağlamak ve kritik kesintileri en aza indirmek için hayati öneme sahiptir.

500 Internal Server Error: Ne Olduğunu Bilmiyor muyuz?

500 Internal Server Error, en genel ve en az bilgilendirici sunucu hatasıdır. Sunucunun isteği işlerken beklenmedik bir durumla karşılaştığını ve isteği tamamlayamadığını belirtir. Bu hata, genellikle yakalanmayan istisnalar, kod hataları veya sunucunun iç mantığındaki sorunlar nedeniyle ortaya çıkar. İstemciye bu hatayı döndürürken, iç hata detaylarını ifşa etmek güvenlik riski oluşturabileceğinden dikkatli olunmalıdır.

Vaka Analizi: Mikroservis Mimarisinde Bir Servis Kesintisi

Bir e-ticaret uygulamasında, ürün detaylarını getiren API'nin, bir arka uçtaki stok servisinden veri alması gerektiğini varsayalım. Eğer stok servisi ulaşılamaz hale gelirse, ürün detayı API'si 500 hatası döndürebilir:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "status": 500,
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Bir hata oluştu, lütfen daha sonra tekrar deneyin."
  // Güvenlik nedeniyle daha fazla detay verilmiyor
}

Bu tür durumlarda, istemciye genel bir hata mesajı sunulmalı, ancak sunucu loglarında hatanın kök nedeni ayrıntılı olarak kaydedilmelidir.

502 Bad Gateway: Proxy veya Gateway Sorunu mu?

502 Bad Gateway, bir sunucunun (genellikle bir proxy veya gateway), yukarı akış (upstream) sunucusundan geçersiz bir yanıt aldığını belirtir. Bu, genellikle bir API gateway'inin veya bir yük dengeleyicinin, arkasındaki gerçek sunuculardan hatalı veya hiç yanıt alamadığı durumlarda meydana gelir.

Kullanım Senaryosu: Nginx gibi bir reverse proxy'nin, arkasındaki uygulama sunucusuna erişememesi.

HTTP/1.1 502 Bad Gateway

Bu hata, genellikle ağ yapılandırması veya arka uç servislerinin kesintiye uğramasıyla ilişkilidir.

503 Service Unavailable: Bakım mı Var, Aşırı Yük mü?

503 Service Unavailable, sunucunun isteği şu anda işleyemediğini belirtir, çünkü sunucu geçici olarak aşırı yüklenmiş veya bakım nedeniyle kullanılamıyor. Bu durum genellikle geçicidir ve sunucuya bir Retry-After başlığı eklenerek istemcilere ne zaman tekrar denemeleri gerektiği bildirilebilir.

Kullanım Senaryosu: API sunucusunun planlı bir bakımda olması veya ani trafik yoğunluğu nedeniyle kaynaklarının yetersiz kalması.

HTTP/1.1 503 Service Unavailable
Retry-After: 3600 // Bir saat sonra tekrar dene

Content-Type: application/json
{
  "status": 503,
  "code": "SERVICE_UNAVAILABLE",
  "message": "API geçici olarak kullanılamıyor. Lütfen bir süre sonra tekrar deneyin."
}

Retry-After başlığı, istemcilerin agresif bir şekilde yeniden deneme yapmasını önleyerek sunucu üzerindeki yükü hafifletmeye yardımcı olur.

504 Gateway Timeout: İstek Zaman Aşımına mı Uğradı?

504 Gateway Timeout, sunucunun (bir gateway veya proxy olarak hareket ederken), yukarı akış sunucusundan zamanında yanıt alamadığını belirtir. Bu, genellikle API'nizin başka bir servisten veri beklerken o servisin çok yavaş yanıt vermesi veya hiç yanıt vermemesi durumunda ortaya çıkar.

Kullanım Senaryosu: Bir API'nin, karmaşık bir rapor oluşturmak için başka bir uzun süreli çalışan arka plan servisine bağımlı olması ve bu servisin belirli bir süre içinde yanıt vermemesi.

HTTP/1.1 504 Gateway Timeout
Content-Type: application/json

{
  "status": 504,
  "code": "GATEWAY_TIMEOUT",
  "message": "İstek işlenirken zaman aşımına uğradı. Lütfen daha sonra tekrar deneyin."
}

5xx hatalarının doğru bir şekilde ele alınması, API'nizin dayanıklılığını ve hata toleransını artırır. Bu hataları proaktif bir şekilde izlemek (monitoring), loglamak ve alarm sistemleriyle entegre etmek, olası kesintileri hızla tespit edip çözmek için kritik öneme sahiptir. İstemcilere doğru 5xx kodlarını ve anlaşılır mesajları döndürmek, onların hatalı istekler göndermesini engellemese de, problemin sunucu tarafında olduğunu bilmelerini sağlayarak gereksiz istemci tarafı hata ayıklama çabalarını önler.

İleri Seviye API Tasarımı İçin Durum Kodlarını Akıllıca Kullanmak

API geliştirme, sadece işlevsellik sağlamakla kalmaz, aynı zamanda kullanıcı dostu, esnek ve sürdürülebilir bir arayüz sunmayı da gerektirir. HTTP durum kodları, bu ileri seviye tasarım prensiplerini destekleyen güçlü bir araçtır. Durum kodlarını akıllıca kullanmak, API'nizin davranışını daha tutarlı hale getirir, hata yönetimini kolaylaştırır ve hatta performansı optimize etmenize yardımcı olabilir.

Özel Hata Mesajları ve Standart Kodlar Arasındaki Denge

Birçok geliştirici, 400 Bad Request veya 500 Internal Server Error gibi genel durum kodlarını döndürüp, hatanın gerçek nedenini yanıt gövdesinde özel bir JSON yapısıyla açıklamayı tercih eder. Bu yaklaşım, hatanın detaylarını istemciye sunarken, HTTP standardına da uyumu korur.

Örnek Bir Hata Yapısı:

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "İstek gövdesindeki veriler geçerli değil.",
  "details": [
    {
      "field": "username",
      "message": "Kullanıcı adı en az 3 karakter olmalı."
    },
    {
      "field": "password",
      "message": "Şifre en az 8 karakter olmalı ve bir rakam içermelidir."
    }
  ],
  "timestamp": "2023-10-27T10:30:00Z"
}

Bu yapı, istemcinin hatayı programatik olarak ayrıştırmasına ve kullanıcı arayüzünde ilgili alanlara yönelik spesifik mesajlar göstermesine olanak tanır. Ancak her özel durum için yeni bir HTTP kodu icat etmek yerine, mevcut 4xx ve 5xx kodlarını genişleten bu tür standartlaştırılmış hata gövdeleri daha pratik ve sürdürülebilirdir.

Idempotency (Tekrarlanabilirlik) ve Durum Kodları

Idempotency, bir isteğin birden fazla kez gönderilmesinin, tek bir kez gönderilmesiyle aynı sonuca sahip olması anlamına gelir. GET, PUT, DELETE gibi HTTP metotları doğaları gereği idempotenttir. POST ise genellikle değildir, çünkü her POST isteği genellikle yeni bir kaynak oluşturur.

Bir API'de PUT veya DELETE isteğiyle bir kaynağı güncellemeye veya silmeye çalışırken, kaynak zaten yoksa veya zaten güncelse ne yapmalısınız?

* PUT/PATCH (Güncelleme): Bir kaynak güncellendiğinde 200 OK veya 204 No Content döndürülmelidir. Eğer güncellemeye çalışılan kaynak mevcut değilse, genellikle 404 Not Found döndürülür. Ancak bazı durumlarda, PUT metodunun "upsert" (varsa güncelle, yoksa oluştur) davranışı göstermesi istenebilir; bu durumda, kaynak yoksa 201 Created döndürülebilir.
* DELETE (Silme): Bir kaynak başarıyla silindiğinde 204 No Content döndürülmelidir. Eğer silinmek istenen kaynak zaten mevcut değilse, yine 404 Not Found döndürmek uygun olabilir. Alternatif olarak, işlemin zaten istenen sonucu verdiğini belirten 200 OK veya 204 No Content döndürmek de kabul edilebilir, zira "kaynağın silinmiş olmasını sağlamak" amacına ulaşılmıştır. Bu son yaklaşım, DELETE'i daha idempotent hale getirir.

// Örnek DELETE endpoint'i
app.delete('/api/urunler/:id', (req, res) => {
  const urunId = req.params.id;
  const silinen = veritabanindanSil(urunId); // Veritabanı işlemi

  if (silinen) {
    res.status(204).send(); // Başarıyla silindi, içerik yok
  } else {
    // Kaynak zaten yoksa veya bulunamazsa
    res.status(404).json({ message: 'Silinecek ürün bulunamadı.' });
    // Alternatif olarak, idempotency için 204 de dönebiliriz.
    // res.status(204).send(); // "Zaten silinmişse de, amaca ulaşıldı"
  }
});

API Versiyonlama ve Durum Kodları

API'nizi versiyonladığınızda (örneğin /api/v1/users, /api/v2/users), eski versiyonların kaldırılması gerektiğinde durum kodları devreye girer. Eski bir versiyon artık desteklenmiyorsa, istemcileri yeni versiyona yönlendirmek için 301 Moved Permanently veya 308 Permanent Redirect kullanılabilir. Ancak bu, istemcilerin eski versiyonu kullanmaya devam etmesini engellemeyebilir. Daha yaygın bir yaklaşım, eski versiyona yapılan isteklere 410 Gone (Kaynak Kalıcı Olarak Kaldırıldı) yanıtı dönerek istemcilerin artık bu kaynağı kullanmaması gerektiğini açıkça belirtmektir.

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "status": 410,
  "code": "API_VERSION_DEPRECATED",
  "message": "Bu API versiyonu artık desteklenmiyor. Lütfen yeni versiyona geçin."
}

Bu, istemcilerin eski entegrasyonlarını güncellemeye zorlar ve API'nizin temiz ve güncel kalmasına yardımcı olur. İleri seviye API tasarımında durum kodlarını bu şekilde stratejik olarak kullanmak, API'nizin sadece işlevsel değil, aynı zamanda robust ve geleceğe dönük olmasını sağlar.

Mobil Uyumlu API Yanıtları ve Hata Yönetimi: Pratik Yaklaşımlar

Mobil uygulamalar, API'lerinizin en yaygın tüketicilerinden biridir. Bu nedenle, API yanıtlarınızın ve özellikle hata mesajlarınızın mobil cihazlarda verimli ve kullanıcı dostu bir şekilde işlenebilir olması büyük önem taşır. Mobil uygulamalar genellikle düşük bant genişliği, değişken ağ koşulları ve kısıtlı işlem gücüyle çalışır, bu da API tasarımında özel yaklaşımlar gerektirir.

JSON Hata Yapıları: Mobil Uygulamalar İçin Standartlaştırma

Daha önce de belirttiğimiz gibi, genel HTTP durum kodlarına ek olarak, yanıt gövdesinde detaylı hata bilgisi sunmak mobil uygulamalar için vazgeçilmezdir. Mobil geliştiricilerin bu hata mesajlarını kolayca ayrıştırıp kullanıcıya anlamlı geri bildirimler sunabilmesi için hata yapılarının standartlaştırılması gerekir.

Önerilen bir JSON hata yapısı şunları içerebilir:

* status: HTTP durum kodu (örn. 400).
* code: Uygulama özelinde bir hata kodu (örn. INVALID_INPUT, USER_EXISTS). Bu, mobil uygulamanın hatayı programatik olarak tanımasına ve özel bir işlem yapmasına olanak tanır.
* message: Geliştirici dostu, kısa bir hata açıklaması.
* details: Hatanın daha spesifik nedenlerini içeren bir dizi (array). Örneğin, hangi alanın yanlış olduğunu veya hangi doğrulama kuralının ihlal edildiğini belirtebilir. Bu, mobil uygulamanın ilgili giriş alanının yanında hatayı göstermesine yardımcı olur.
* timestamp: Hatanın ne zaman oluştuğunu belirten zaman damgası.
* traceId: Eğer bir distributed tracing (dağıtık izleme) sistemi kullanılıyorsa, hatayı loglarda bulmayı kolaylaştıran bir izleme kimliği.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "status": 400,
  "code": "VALIDATION_FAILED",
  "message": "Gönderilen veriler doğrulama kurallarını karşılamıyor.",
  "details": [
    {
      "field": "username",
      "error": "Kullanıcı adı boş bırakılamaz."
    },
    {
      "field": "email",
      "error": "Geçersiz e-posta formatı."
    }
  ],
  "timestamp": "2023-10-27T11:00:00Z",
  "traceId": "abc123def456"
}

Mobil uygulama, bu yapıyı kullanarak hata mesajlarını kullanıcıya anlaşılır bir dilde ve doğru bağlamda sunabilir (örneğin, kullanıcı adı alanının altında "Kullanıcı adı boş bırakılamaz" uyarısını göstermek).

Mobil Uygulamalarda Hata Görüntüleme ve Kullanıcı Deneyimi

Mobil uygulamaların hata yönetimi, kullanıcı deneyimini doğrudan etkiler. API'den gelen 4xx ve 5xx hatalarını nasıl yöneteceğinize dair bazı ipuçları:

1. Anlaşılır Mesajlar: API'den gelen teknik hata mesajlarını doğrudan kullanıcıya göstermek yerine, daha kullanıcı dostu ve anlaşılır mesajlara çevirin. Örneğin, "VALIDATION_FAILED" kodunu "Girdiğiniz bilgilerde bir sorun var" olarak çevirin.
2. Bağlam Sağlayın: Hatanın nerede olduğunu belirtin. Eğer bir formda hata varsa, ilgili giriş alanının yanında gösterin. Genel bir hata ise, geçici bir bildirim (snackbar, toast) veya hata ekranı kullanın.
3. Tekrar Deneme Seçeneği: Özellikle 5xx hataları ve bazı 4xx hataları (örn. 429 Too Many Requests) için kullanıcıya "Tekrar Dene" veya "Yenile" seçeneği sunun. Ancak, 401 veya 403 gibi kalıcı hatalar için bu mantıklı olmayabilir; bu durumda kullanıcıyı oturum açma sayfasına yönlendirmek daha uygun olabilir.
4. Uygulama İçi Hata Kaydı: Mobil uygulamanın kendisinde de kritik hataları loglayarak veya hata izleme araçlarına (Firebase Crashlytics, Sentry) göndererek API hatalarının mobil taraftaki etkilerini izleyin.

Mobil Uyumlu HTML ve Hata Mesajları için Stil Örnekleri (API'ye Dolaylı Yaklaşım)

Her ne kadar API'ler genellikle JSON veya XML yanıtları dönse de, bazı durumlarda API'nizden gelen bir yanıtın doğrudan bir web görünümünde veya hata sayfasında gösterilmesi gerekebilir. Bu senaryolarda, mobil uyumlu HTML stilleri kullanmak, hata mesajlarının farklı ekran boyutlarında doğru görüntülenmesini sağlar.

Aşağıdaki CSS örneği, bir hata mesajı kapsayıcısının mobil cihazlarda nasıl daha küçük yazı tipleriyle ve uygun dolgularla görüntülenebileceğini gösterir:

  
Bir Hata Oluştu!
  
Beklenmedik bir durumla karşılaşıldı. Lütfen birkaç dakika sonra tekrar deneyin veya destek ekibimizle iletişime geçin.
  

    
Hata Kodu: INTERNAL_SERVER_ERROR
    
Zaman: 2023-10-27 11:05:30
  

Bu HTML ve CSS örneği, doğrudan bir API yanıtı olmasa da, mobil uygulamaların veya web görünümlerinin API'den gelen hataları kullanıcıya nasıl sunabileceğine dair genel bir çerçeve sunar. API'nizin doğrudan HTML döndürmesi yerine, hata mesajlarınızın anlamlı JSON yapılarıyla döndürülmesi ve bu yapıların mobil uygulama tarafından uygun şekilde işlenerek kullanıcıya sunulması, modern API geliştirme pratiklerinin temelini oluşturur.

Mobil uyumlu API yanıtları ve etkili hata yönetimi, uygulamanızın sadece çalışmasını değil, aynı zamanda zorlu koşullarda bile kullanıcılarına sorunsuz bir deneyim sunmasını sağlar.

Sonuç ve Sıkça Sorulan Sorular

HTTP durum kodları, modern API geliştirmenin temel taşlarından biridir. Bu makale boyunca, bu üç haneli sayıların yalnızca hata ayıklama aracı olmanın ötesinde, API'lerinizin netliğini, güvenilirliğini ve kullanıcı deneyimini nasıl şekillendirdiğini inceledik. 1xx'den 5xx'e kadar uzanan farklı sınıflardaki kodları anlayarak ve bunları doğru senaryolarda kullanarak, API'niz ve onu tüketen uygulamalar arasında güçlü, anlamlı bir iletişim köprüsü kurmuş olursunuz.

Başarılı yanıtlar (2xx) istemcilere "işlem tamamlandı" mesajını verirken, yönlendirme kodları (3xx) kaynakların hareketliliğini yönetmemize yardımcı olur. İstemci hataları (4xx), istemcinin isteğindeki sorunları işaret ederek onların daha doğru istekler yapmasını teşvik eder. Sunucu hataları (5xx) ise, API'nizin iç sağlığını gösterir ve acil müdahale gerektiren sorunları belirginleştirir.

Unutulmamalıdır ki, iyi bir API, sadece istenen veriyi döndüren değil, aynı zamanda bir şeyler ters gittiğinde veya ek bilgi gerektiğinde de doğru ve açıklayıcı yanıtlar veren bir API'dir. Hata mesajlarınızı standartlaştırmak, idempotentliği sağlamak, API versiyonlamasını durum kodlarıyla desteklemek ve mobil uyumlu hata yapıları sunmak, API'nizin uzun vadeli başarısı için kritik adımlardır. Bu prensiplere bağlı kalmak, hem geliştirici verimliliğini artıracak hem de API'nizi kullanan son kullanıcılar için sorunsuz ve güvenilir bir deneyim sağlayacaktır.

Sıkça Sorulan Sorular

1. API geliştirirken hangi HTTP durum kodlarını en sık kullanmalıyım?

   En sık kullanacağınız kodlar genellikle şunlardır: 200 OK (genel başarı), 201 Created (yeni kaynak oluşturma), 204 No Content (içeriksiz başarı, örn. silme), 400 Bad Request (genel istemci hatası), 401 Unauthorized (kimlik doğrulama hatası), 403 Forbidden (yetkilendirme hatası), 404 Not Found (kaynak bulunamadı) ve 500 Internal Server Error (genel sunucu hatası).

2. Bir isteğin başarılı olduğu ancak yanıt gövdesine gerek olmadığı durumlarda hangi kodu kullanmalıyım?

   Bu durumda 204 No Content kodunu kullanmalısınız. Özellikle DELETE işlemleri veya bir kaynağın başarılı bir şekilde güncellendiği ancak güncel verinin geri döndürülmesinin gerekli olmadığı PUT/PATCH işlemleri için idealdir. Bu, ağ trafiğini de azaltır.

3. 401 Unauthorized ve 403 Forbidden arasındaki fark nedir?

   401 Unauthorized, istemcinin kimlik doğrulaması yapmadığını veya geçersiz kimlik bilgileri sunduğunu belirtir. Yani, sunucu "kimsin sen?" diye sorar. 403 Forbidden ise, istemcinin kim olduğunu bildiğini ancak o kaynağa erişim veya o eylemi gerçekleştirme yetkisine sahip olmadığını belirtir. Yani, sunucu "kim olduğunu biliyorum ama bunu yapmana izin vermiyorum" der.

4. 500 Internal Server Error durumunda istemciye ne tür bir yanıt vermeliyim?

   500 Internal Server Error döndürürken, güvenlik nedeniyle sunucunun iç hata detaylarını doğrudan istemciye ifşa etmemelisiniz. Bunun yerine, "Bir hata oluştu, lütfen daha sonra tekrar deneyin" gibi genel, kullanıcı dostu bir mesaj ve isteği izleyebilmek için bir traceId veya hata referans kodu döndürmek en iyisidir. Hatanın tüm detaylarını sunucu tarafındaki loglarda tutmalısınız.

5. API'mde oransal sınırlama (rate limiting) uyguluyorum. Bir istemci sınırı aştığında hangi kodu döndürmeliyim?

   Oransal sınırlama aşıldığında 429 Too Many Requests durum kodunu döndürmelisiniz. Ayrıca, istemciye ne kadar süre sonra tekrar istek yapabileceğini bildiren bir Retry-After HTTP başlığı da eklemeniz önerilir. Bu, istemcinin yeniden deneme mantığını daha akıllı hale getirir.