Web Development

HTTP HEAD for Small Web Applications - Keep GET Semantics Without Sending Content

HTTP HEAD for Small Web Applications - Keep GET Semantics Without Sending Content

How can a client inspect a URL without downloading its representation? HTTP has a method for that: HEAD. It is often described as “GET without the body,” which is a useful first approximation. It is not quite a complete implementation guide, however. The difficult part is not suppressing output. It is preserving the meaning of the response when status codes, redirects, authentication, content negotiation, and metadata all enter the picture.

A reliable HEAD implementation should answer the same question as GET: what would happen if this client requested this resource? The difference is that it returns the answer as status and metadata without sending the selected representation. That makes HEAD useful, but it also limits what the response can prove.

The Contract Is GET Semantics Without Response Content

RFC 9110 defines HEAD as identical to GET except that the server must not send content in the response. “Identical” concerns the request's semantics, not a requirement that every byte of the two response header sections be equal.

Suppose GET /manual.pdf would select a PDF, require authentication, and return 200 OK. A corresponding HEAD request should not be routed to a generic success response merely because no file bytes are needed. It should still encounter the same resource selection and authorization decisions. If the resource moved, the redirect still matters. If it does not exist, 404 Not Found still matters. If access is denied, the response should not pretend otherwise.

The method is classified as safe and idempotent. “Safe” means its defined semantics are read-only; it does not promise that the server performs no incidental work. Access logging, rate accounting, cache activity, or session housekeeping can still occur. A route must not turn a nominally safe request into a hidden state-changing command.

Headers Should Match, but Not at Any Cost

The specification says a server should send the same header fields for HEAD that it would send for GET. It also allows a server to omit fields whose values are known only while generating the content. This qualification prevents an odd optimization: rendering or reading an entire large representation, counting its bytes, and then throwing those bytes away merely to make one header available.

Content-Length is the common trap. A server may send it in a HEAD response, but its value must describe the content length that a corresponding GET would have sent. It is not the length of the HEAD response content, because that content does not exist. If the application cannot know the final encoded length without generating the representation, omitting the field is more honest than guessing.

The same caution can apply to metadata decided late in generation. RFC 9110 gives Vary as another possible example. This does not excuse casually divergent responses. Stable metadata such as the selected Content-Type, cache policy, validators, language, redirect location, and authentication challenge should remain consistent whenever the application can determine them through the normal request path.

What HEAD Can and Cannot Tell a Client

A client can use HEAD to inspect a status, follow a resource's redirects, compare an ETag or Last-Modified value, or learn available representation metadata without transferring the representation itself. Link checkers and download tools can use that information as one input to a decision.

But a successful HEAD response does not prove that a later GET body will transfer completely. The underlying file might disappear after the metadata check. A dynamic renderer might fail only when producing content. Authorization might change between requests. A server might simply implement HEAD incorrectly. There is an unavoidable time gap between asking about a representation and retrieving it.

It also does not guarantee a cheap request. A database-backed page may need routing, authorization, a row lookup, and content negotiation before it knows the correct status and headers. The server saves response bytes and might avoid rendering work, but the amount saved depends on the application. There is no responsible universal performance multiplier to attach to the method.

HEAD Has a Narrow but Real Cache Role

HEAD responses are cacheable. More specifically, RFC 9111 explains how a cache can use HEAD to update or invalidate a stored GET response. If validators such as ETag or Last-Modified match, and a supplied Content-Length also matches, the cache can update stored metadata. A mismatch can make the stored response stale.

This is not a reason to replace every conditional GET with HEAD. When a stored response has validators, a conditional GET directly asks whether that representation is still current and can receive 304 Not Modified. RFC 9111 describes HEAD as useful when that more efficient validation route is unavailable or when receiving changed content is undesirable. Cache behavior is part of the method's semantics, not proof that every deployed cache will make the same optimization.

One Request Path Is Safer Than Two Implementations

The most maintainable application design is usually to share resource selection, authorization, status, and metadata logic between GET and HEAD. Only the final content emission should differ. The following simplified PHP pattern illustrates the boundary:

<?php
$method = $_SERVER['REQUEST_METHOD'] ?? 'GET';

if (!in_array($method, ['GET', 'HEAD'], true)) {
    header('Allow: GET, HEAD');
    http_response_code(405);
    exit;
}

$article = findPublishedArticle($_SERVER['REQUEST_URI']);

if ($article === null) {
    http_response_code(404);
    exit;
}

header('Content-Type: text/html; charset=UTF-8');
header('Cache-Control: public, max-age=300');
header('ETag: "' . $article['etag'] . '"');

if ($method === 'HEAD') {
    exit;
}

echo renderArticle($article);

This is a routing sketch, not a drop-in framework. The two named functions and the validator generation need application-specific implementations. Its important property is ordering: method handling does not bypass route lookup or status selection, while expensive HTML rendering occurs only for GET. Because the final HTML length is not known before rendering, the example deliberately sends no Content-Length.

A static-file server or an application with a stored, already encoded representation can know the length cheaply. A streaming page often cannot. Those cases should not be forced into the same metadata strategy.

Test the Method and the Final Destination

curl provides a proper HEAD mode with -I or --head:

curl --head https://example.com/article
curl --head --location https://example.com/article

The second command follows redirects. Without --location, the first redirect response may be exactly what curl should show, but it does not describe the final destination. When testing a multilingual route, login boundary, or canonical redirect, inspect the whole chain rather than only its first status.

To compare the result with a real GET while keeping its body out of the terminal, request normally and discard the downloaded content:

curl --silent --show-error \
  --dump-header - \
  --output /dev/null \
  https://example.com/article

This command still transfers the GET representation; /dev/null only discards it locally. Compare the status and relevant fields, not volatile values such as Date or tracing IDs.

A subtle curl mistake is curl -X HEAD URL. The curl manual explains that --request only changes the method word; it does not switch curl to the transfer behavior used by --head. Use --head when the goal is a proper HTTP HEAD operation.

Common Failure Modes

A Separate “Fast” Route Drifts from GET

A handcrafted HEAD branch might return 200 before authorization, canonical redirects, locale selection, or database lookup. It is fast because it answers a different question. Sharing the decision path reduces this drift.

The Application Generates a Fake Length

A template's source length is not necessarily the transmitted representation length. Character encoding, content encoding, middleware, and late rendering can change the bytes. Omit Content-Length unless the value corresponds to the actual selected GET representation.

The Server Renders Everything and Discards It

This can produce precise metadata, but it gives up much of the potential efficiency. Decide which metadata is available before rendering and use the specification's permitted omissions where necessary.

Monitoring Treats HEAD as Complete Health Evidence

HEAD can verify reachability and metadata behavior. It cannot exercise complete body generation, streaming, or client-side execution. A useful monitor chooses a request that matches the failure it is intended to detect; sometimes that is HEAD, and sometimes only a real GET is adequate.

A Practical Review Checklist

  • Route HEAD through the same resource, authorization, redirect, and representation-selection decisions as GET.
  • Never send response content for HEAD.
  • Keep status and stable metadata aligned with the corresponding GET.
  • Do not invent Content-Length or other late-computed fields.
  • Prevent safe-method routes from performing intended state changes.
  • Test direct responses, redirect chains, missing resources, and protected resources.
  • Use curl --head, not merely -X HEAD.
  • Retain at least one real GET check when complete representation delivery matters.

Conclusion

HEAD is small in syntax but not trivial in meaning. Its value comes from preserving the decisions of GET while withholding response content. The honest implementation is therefore not a universal 200 OK shortcut. It is a shared request path with a carefully placed boundary before content generation or emission.

That boundary can save bandwidth and sometimes application work. It cannot guarantee a future download, replace every conditional request, or make expensive metadata free. Treating those limits as part of the design makes HEAD more useful, not less.

References