ETag Nedir? HTTP Cache ile API’yi Hızlandırın

Meta Description

ETag nedir, nasıl çalışır? 304 Not Modified ile API trafiğini azaltın. Express.js örneğiyle 30 dakikada HTTP cache kurun.

Giriş (Introduction)

Aynı veriyi tekrar tekrar dönen bir API, hem sunucu maliyetini hem de sayfa/uygulama açılış süresini gereksiz yere şişirir. Üstelik çoğu zaman veri değişmemiştir; ama istemci yine de tam yanıtı indirir.

İşte burada ETag devreye girer. ETag, HTTP seviyesinde “Bu içerik değişti mi?” sorusunu çok düşük maliyetle yanıtlayarak 304 Not Modified üzerinden bant genişliği ve CPU tasarrufu sağlar.

Bu yazıda ETag nedir, If-None-Match ile nasıl çalışır, hangi durumlarda kullanılmalı ve Express.js ile adım adım nasıl uygulanır, net bir şekilde öğreneceksiniz.

ETag Nedir? (Anahtar kelime)

ETag (Entity Tag), bir kaynağın (response body) belirli bir sürümünü temsil eden benzersiz bir etikettir. Sunucu, yanıtla birlikte bir ETag gönderir. İstemci aynı kaynağı tekrar isterken If-None-Match başlığına bu ETag’i ekler.

• Eğer içerik değişmediyse: Sunucu 304 Not Modified döner (body göndermez).
• Eğer içerik değiştiyse: Sunucu 200 OK + yeni body + yeni ETag döner.

Bu sayede özellikle:

• mobil uygulamalar,
• SPA/SSR web uygulamaları,
• CDN arkasındaki API’ler,
• dashboard ve liste ekranları

çok daha hızlı hissedilir.

ETag Nasıl Çalışır? (If-None-Match ve 304)

Temel istek/yanıt akışı

1. İlk istek:

• İstemci: GET /api/products/42
• Sunucu: 200 OK + body + ETag: "v1-abc123"

1. İkinci istek:

• İstemci: GET /api/products/42 + If-None-Match: "v1-abc123"
• Sunucu:
  • içerik aynıysa: 304 Not Modified (body yok)
  • farklıysa: 200 OK + yeni body + yeni ETag

Örnek HTTP başlıkları

GET /api/products/42 HTTP/1.1
Host: example.com
If-None-Match: "v1-abc123"

HTTP/1.1 304 Not Modified
ETag: "v1-abc123"
Cache-Control: private, max-age=0

Neden önemli? 304 yanıtı genellikle çok küçük olduğu için ağ ve CPU tüketimi dramatik biçimde düşer.

Strong vs Weak ETag: Hangisini Ne Zaman Kullanmalı?

ETag iki temel tiptir:

Pratik öneri: API JSON yanıtlarında çoğunlukla strong ETag tercih edilir. İçerik değiştiğinde ETag de değişsin istersiniz.

Bunu Neden Yapmalıyım? (Performans ve Maliyet Etkisi)

ETag’in etkisi özellikle sık okunan ama seyrek değişen kaynaklarda büyür:

• Bant genişliği azalır: Aynı response body tekrar gönderilmez.
• Sunucu CPU’su düşer: (Doğru kurguda) daha az serialization, daha az iş.
• Daha hızlı UX: Mobil ağlarda hissedilir hız artışı.
• CDN ve proxy uyumu: HTTP cache katmanlarıyla iyi çalışır.

Gerçek hayattan örnek:

• E-ticaret “ürün detayı” endpoint’i günde 1M kez çağrılıyor, ürün içeriği günde 1-2 kez değişiyor.
• ETag ile kullanıcıların büyük çoğunluğu 304 alır.
• Sonuç: ciddi trafik ve maliyet tasarrufu.

ETag Üretme Stratejileri (En Sağlıklısı Hangisi?)

ETag üretmenin 3 yaygın yöntemi:

1) İçerik hash’i (body’den hash)

• Artı: Doğru ve otomatik.
• Eksi: Büyük response’larda hash maliyeti.

2) Versiyon alanı / updatedAt tabanlı

• Artı: En ucuz yöntem.
• Eksi: Doğru modelleme gerektirir.

Önerilen format:

• ETag = <resourceId>:<updatedAtEpoch>

3) Veritabanı row version (xmin, rowversion vb.)

• Artı: Çok hızlı.
• Eksi: DB bağımlılığı ve taşınabilirlik sorunu.

Altın kural: ETag “içerik değişti” bilgisini güvenilir taşımalı. En pratik yaklaşım çoğu sistemde updatedAt + id kombinasyonudur.

Express.js ile ETag Uygulaması (Adım Adım)

Aşağıdaki örnekte updatedAt üzerinden güçlü bir ETag üretiyoruz. Eğer istemci aynı ETag’i gönderirse 304 dönüyoruz.

1) Örnek endpoint

import express from "express";

const app = express();

// Sahte veri
const product = {
  id: 42,
  name: "Mekanik Klavye",
  price: 3499,
  updatedAt: "2026-01-15T10:20:00.000Z"
};

function toEtagFromUpdatedAt(entity) {
  // Basit ve hızlı: id + updatedAt
  // Strong ETag için çift tırnakla gönderiyoruz
  return `"${entity.id}:${new Date(entity.updatedAt).getTime()}"`;
}

app.get("/api/products/:id", (req, res) => {
  // Normalde DB'den okuyacaksınız
  const data = product;

  const etag = toEtagFromUpdatedAt(data);
  res.setHeader("ETag", etag);
  res.setHeader("Cache-Control", "private, max-age=0");

  const inm = req.headers["if-none-match"];
  if (inm && inm === etag) {
    return res.status(304).end();
  }

  return res.json(data);
});

app.listen(3000, () => console.log("Listening on :3000"));

2) Test (curl)

İlk istek:

curl -i http://localhost:3000/api/products/42

İkinci istek (ETag’i kopyalayıp gönderin):

curl -i http://localhost:3000/api/products/42 \
  -H 'If-None-Match: "42:1768472400000"'

Beklenen: İkinci istekte 304 Not Modified dönmesi.

ETag Kullanırken Dikkat Edilmesi Gerekenler

1) Kişiye özel (personalized) içerikte cache politikası

Kullanıcıya özel yanıtlar dönüyorsanız:

• Cache-Control: private kullanın.
• Gerekirse Vary: Authorization veya Vary: Cookie ekleyin.

Aksi halde yanlış kullanıcıya yanlış içerik “cache”lenebilir.

2) ETag ile Last-Modified birlikte kullanılabilir

Last-Modified + If-Modified-Since daha kaba bir mekanizmadır. ETag daha hassastır. İkisi birlikte konulabilir, ama çakışma kurallarını iyi belirlemek gerekir.

3) Cluster/Load balancer arkasında tutarlılık

ETag üretimi node’a göre değişmemeli. Örneğin body hash’i kullanıyorsanız JSON alan sırası gibi detaylar ETag’i gereksiz değiştirir. Deterministik üretin.

4) CDN ve reverse proxy davranışı

CDN kullanıyorsanız Cache-Control, Surrogate-Control gibi başlıkları ayrıca tasarlayın. ETag tek başına “CDN’de cachele” demek değildir.

Sık Sorulan Sorular (FAQ)

1) ETag nedir, ne işe yarar?

ETag, bir kaynağın sürüm etiketidir. İstemci If-None-Match ile gönderir; içerik aynıysa sunucu 304 döner ve body göndermeden hız kazandırır.

2) ETag SEO’yu etkiler mi?

Dolaylı olarak evet. Daha hızlı yanıt süreleri ve daha düşük yük, Core Web Vitals ve tarama verimliliğine katkı sağlayabilir.

3) ETag mi Last-Modified mı kullanmalıyım?

Değişiklik tespiti hassas olsun istiyorsanız ETag daha güçlüdür. Basit dosya/HTML senaryolarında Last-Modified yeterli olabilir.

4) ETag güvenlik riski oluşturur mu?

Yanlış kurgulanırsa olabilir. Kullanıcıya özel içerikte ortak cache’e düşmesini engellemek için Cache-Control: private ve uygun Vary başlıklarını kullanın.

5) ETag her endpoint için uygun mu?

Hayır. Çok sık değişen veya response üretimi zaten çok ucuz olan endpoint’lerde getirisi düşük olabilir. En iyi sonuç: sık okunan, seyrek değişen kaynaklarda.

Sonuç

ETag, HTTP seviyesinde uygulayabileceğiniz en pratik performans optimizasyonlarından biri. Doğru tasarlandığında If-None-Match + 304 Not Modified ile hem istemciyi hızlandırır hem de sunucu maliyetini düşürür.

Bugün şunu yapın: En çok trafik alan 1 endpoint’i seçin, updatedAt tabanlı ETag ekleyin ve 304 oranını ölçün.

Denediğiniz senaryoyu (hangi endpoint, ne kadar 304 gördünüz, hangi başlıkları kullandınız) yorum olarak yazın; birlikte iyileştirelim.