ETag: ce este, mecanismul de stocare în cache și configurarea antetului

Ce este ETag?

ETag (Entity Tag) — este un antet de răspuns HTTP care conține un identificator unic al unei versiuni specifice de resursă. Serverul calculează ETag pe baza conținutului fișierului, a metadatelor sale sau a numărului de revizie și îl transmite clientului în răspunsul la o solicitare GET. Clientul salvează acest identificator și la solicitările ulterioare către aceeași resursă îl trimite în antetul If-None-Match. Dacă resursa nu s-a schimbat, serverul răspunde cu 304 Not Modified, iar clientul folosește copia stocată în cache.

Formatul ETag este definit în RFC 7232 ca un șir între ghilimele: "33a64df551425fcc55e4d42a148795d9f25f89d4". Valoarea poate fi un hash SHA-1 al conținutului fișierului, un număr de versiune incremental, o combinație inode-număr-timp pentru fișiere statice sau orice token generat de server. Singura cerință este ca valoarea să se schimbe la orice modificare a resursei și să nu se schimbe dacă resursa a rămas aceeași.

ETag face parte din mecanismele de solicitări condiționate (conditional requests) — una dintre optimizările de bază ale protocolului HTTP. Spre deosebire de solicitările necondiționate, unde serverul returnează întotdeauna un răspuns complet, o solicitare condiționată permite clientului să verifice actualitatea cache-ului fără a reîncărca datele. Conform datelor HTTP Archive (2025), aproximativ 40% din toate răspunsurile HTTP sunt 304 Not Modified datorită configurării corecte a ETag și Last-Modified.

Unde se aplică ETag

ETag este utilizat în REST API pentru optimizarea încărcării colecțiilor de date — dacă lista de obiecte nu s-a schimbat, clientul primește 304 fără a transmite întregul JSON. În fișierele statice (CSS, JS, imagini) ETag permite CDN-urilor și browserelor să verifice eficient actualitatea cache-ului. În aplicațiile mobile, ETag este critic pentru sincronizarea în fundal: aplicația verifică dacă datele de pe server s-au schimbat și descarcă actualizările doar atunci când este necesar. Aceasta economisește trafic și bateria dispozitivului.

Cum funcționează ETag?

Ciclul complet de funcționare a ETag constă în patru pași. Serverul generează ETag la prima solicitare și îl returnează în antetul răspunsului. Clientul salvează ETag împreună cu resursa stocată în cache. La o solicitare repetată, clientul trimite antetul If-None-Match cu valoarea ETag-ului salvat. Serverul compară valoarea primită cu ETag-ul curent al resursei: în caz de potrivire, returnează 304 Not Modified cu corp gol, în caz de nepotrivire — 200 OK cu o resursă nouă și un ETag nou.

// Solicitarea clientului cu If-None-Match
GET /api/users HTTP/1.1
Host: example.com
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

// Răspunsul serverului — resursa nu s-a schimbat
HTTP/1.1 304 Not Modified
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

Într-o aplicație mobilă, acest ciclu poate fi implementat printr-un client HTTP cu suport pentru cache. OkHttp, de exemplu, gestionează automat ETag prin CacheInterceptor: salvează ETag-ul răspunsului și la o solicitare repetată adaugă If-None-Match. La primirea unui 304, OkHttp returnează datele stocate în cache. OkHttp suportă ETag fără configurare suplimentară — este suficient să activați cache-ul prin OkHttpClient.Builder.cache().

Generarea ETag pe server

Serverul poate calcula ETag în diferite moduri: prin hash MD5 sau SHA al conținutului, prin numărul de revizie din baza de date (de exemplu, updated_at din MySQL), printr-o combinație inode + mtime + size pentru fișiere statice (Nginx generează ETag exact în acest fel). Pentru API-urile dinamice, cel mai fiabil este hash-ul conținutului: dacă răspunsul JSON a schimbat măcar un câmp, ETag se va schimba. Cu toate acestea, calcularea hash-ului la fiecare solicitare încarcă procesorul — pentru sistemele cu încărcare mare, este mai bine să utilizați un număr de versiune incremental.

ETag puternice și slabe

RFC 7232 definește două tipuri de ETag: puternice (strong) și slabe (weak). Un ETag puternic înseamnă că două reprezentări ale resursei sunt identice byte cu byte — niciun bit nu diferă. Un ETag slab (prefixul W/) garantează doar echivalența semantică: conținutul poate diferi la nivel de serializare (spații, ordinea câmpurilor JSON), dar datele sunt considerate aceleași pentru client. ETag-urile slabe sunt marcate cu prefixul W/, de exemplu W/"1a2b3c".

Alegerea tipului de ETag depinde de cerințele de precizie ale comparației. Pentru fișierele statice (CSS, JS, imagini) sunt preferate ETag-urile puternice — dacă fișierul s-a schimbat, clientul trebuie să primească versiunea nouă. Pentru API-urile dinamice, unde același JSON poate fi serializat cu o ordine diferită a câmpurilor sau formatare, ETag-urile slabe oferă mai multă flexibilitate: serverul generează ETag pe baza datelor de business, nu a reprezentării șirului.

Limitarea ETag-urilor slabe: nu pot fi utilizate cu solicitări de interval (Range requests). Dacă clientul solicită o parte a fișierului, serverul trebuie să returneze un ETag puternic pentru a garanta că fragmentul corespunde resursei complete. ETag-urile slabe nu oferă o astfel de garanție. În celelalte scenarii, ETag-urile slabe sunt sigure și recomandate pentru API-uri.

ETag vs Last-Modified

ETag și Last-Modified sunt două antete HTTP pentru solicitări condiționate care sunt adesea utilizate împreună. Last-Modified indică data ultimei modificări a resursei și funcționează cu antetul If-Modified-Since. ETag oferă un identificator unic de versiune și funcționează cu If-None-Match. Fiecare are avantajele și limitările sale, iar combinația oferă eficiență maximă a stocării în cache.

Last-Modified este mai simplu de implementat — serverul obține automat data din sistemul de fișiere sau actualizează câmpul updated_at în baza de date. Cu toate acestea, data are o precizie de până la o secundă, ceea ce este insuficient pentru resursele care se schimbă de mai multe ori pe secundă. În plus, Last-Modified nu distinge diferite stări: dacă fișierul este suprascris cu aceeași versiune, data se schimbă, dar conținutul nu — clientul reîncarcă date identice.

ETag este mai precis: se schimbă doar la modificarea reală a conținutului. Dacă serverul a restaurat versiunea anterioară din backup, ETag se va schimba. Dacă fișierul este suprascris cu aceleași date — ETag rămâne același, iar clientul nu va reîncărca. Utilizarea împreună este recomandată de specificația HTTP: serverul returnează ambele antete, clientul trimite If-None-Match și If-Modified-Since simultan. Dacă cel puțin un antet indică o schimbare — serverul returnează o resursă nouă.

Prioritatea antetelor

Conform specificației, ETag are prioritate față de Last-Modified. Dacă serverul a primit If-None-Match, trebuie să verifice doar ETag, ignorând If-Modified-Since. Aceasta previne race condition: dacă resursa s-a schimbat între momentul trimiterii Last-Modified de către client și verificarea pe server, ETag va fi un indicator mai proaspăt. În practică, serverele verifică de obicei ambele antete, dar în caz de neconcordanță a rezultatelor, ETag câștigă.

Implementarea ETag pe server

Configurarea ETag depinde de tipul serverului. Nginx generează ETag pentru fișierele statice automat pe baza inode, mtime și dimensiunii. Apache utilizează mecanismul FileETag. Pentru aplicațiile dinamice în Node.js, PHP, Python, Ruby, ETag trebuie generat programatic — prin hash-ul răspunsului, numărul de versiune al datelor sau o combinație de parametri ai solicitării.

func etagMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter,
        r *http.Request) {
        // Generarea ETag pe baza datelor
        etag := generateETag(r.URL.Path)
        w.Header().Set("ETag", etag)

        // Verificarea If-None-Match
        if r.Header.Get("If-None-Match") == etag {
            w.WriteHeader(http.StatusNotModified)
            return
        }
        next.ServeHTTP(w, r)
    })
}

Middleware-ul Go interceptează solicitarea, generează ETag pentru URL-ul solicitat (de exemplu, calculează hash-ul datelor din cache sau din baza de date) și setează antetul răspunsului. Dacă clientul a trimis If-None-Match și acesta se potrivește cu ETag-ul curent, serverul returnează imediat 304 Not Modified, fără a apela handler-ul principal. în producție, merită să adăugați stocarea în cache a ETag-urilor calculate după URL și parametri pentru a reduce încărcarea serverului.

Probleme și capcane

Într-o configurație multi-server (round-robin sau anycast) ETag trebuie să fie același pe toate nodurile pentru aceeași resursă. Dacă ETag este generat pe baza inode-ului fișierului, iar site-ul rulează pe mai multe servere, valorile vor diferi. Soluția — utilizarea hash-ului conținutului sau a unei stocări centralizate a versiunilor (Redis, etcd). A doua problemă — compresia gzip: Nginx schimbă ETag atunci când compresia este activată, ceea ce poate cauza 304-uri excesive. Este necesară configurarea gzip_vary on pentru sincronizarea ETag cu conținutul comprimat.