Master API Caching: ETags & Stale-While-Revalidate

The Redundant Data Tax

In data-dense B2B SaaS platforms at Smart Tech Devs, clients constantly poll your API for updates. Imagine a dashboard making a GET /api/system-config request every 60 seconds. The payload is 200KB of JSON. If the configuration hasn't changed in three days, your server is spending CPU cycles serializing data, and you are paying AWS egress fees to transmit the exact same 200KB file 1,440 times a day per user.

Basic Redis caching speeds up the database query, but it doesn't stop the payload from traveling over the network. To eliminate network bloat entirely, your API must leverage the browser's native HTTP cache using ETags and the Stale-While-Revalidate directive.

The Solution: 304 Not Modified

An ETag (Entity Tag) is a cryptographic hash (like an MD5 checksum) of the response body. When the server sends the JSON, it includes the ETag in the header.

The next time the browser requests that endpoint, it sends an If-None-Match: {ETag} header. The server quickly calculates the hash of the current data. If the hashes match, the data hasn't changed! Instead of sending the 200KB JSON body, the server instantly drops the payload and replies with a tiny, empty 304 Not Modified status code. The browser knows it is safe to use its local cache, dropping network transfer times to 1 millisecond.

Architecting an ETag Middleware in Laravel

We can implement this globally across our read-only API routes using a custom Laravel Middleware layer.

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class ETagCacheMiddleware
{
    public function handle(Request $request, Closure $next)
    {
        // 1. Only cache safe, read-only methods
        if (! $request->isMethod('GET') && ! $request->isMethod('HEAD')) {
            return $next($request);
        }

        $response = $next($request);

        // 2. Generate a unique MD5 hash of the final JSON content
        $etag = md5($response->getContent());
        $requestEtag = str_replace('"', '', $request->header('If-None-Match', ''));

        // 3. If the browser's hash matches the server's hash, drop the payload!
        if ($requestEtag === $etag) {
            $response->setNotModified(); // Automatically converts to 304 and strips the body
        }

        // 4. Attach the ETag and the ultimate performance directive: stale-while-revalidate.
        // This tells the browser: "Show the cached version instantly, but check the server in the background for updates."
        $response->withHeaders([
            'ETag' => '"' . $etag . '"',
            'Cache-Control' => 'public, max-age=60, stale-while-revalidate=300'
        ]);

        return $response;
    }
}

The Engineering ROI

By implementing ETags and stale-while-revalidate, you shift the burden of data storage from your cloud servers to your user's local device. Your server response times become functionally instantaneous, network bandwidth costs plummet, and your Next.js frontend feels locally native because it never waits for unchanged data to cross the physical wire.