HEAD /resource

API Design

Meaning

The HTTP HEAD method requests the headers that a GET request to the same resource would return, but transfers no response body. It addresses the need to inspect resource metadata (size, existence, modification time, content type) without paying the bandwidth cost of the full payload. Triggered when validating caches, probing link health, or checking resource state before committing to a download.

Primary Function

HTTP request method

Communicative Purpose

Retrieves resource metadata without downloading the response body, enabling efficient cache validation and existence checks.

Pattern

HEAD /resource HTTP/1.1

Core Structure

HEAD /resource

Função primária

HTTP request method

Propósito comunicativo

Retrieves resource metadata without downloading the response body, enabling efficient cache validation and existence checks.

Situações de gatilho

REST APIs: checking if a resource exists or has been modified before issuing a full GET CDN/proxy caching: validating cached resources with conditional headers like If-Modified-Since Web crawlers: probing link health and content size without transferring full pages

Contextos

REST APIs, HTTP clients (requests, curl, fetch), web crawlers, CDN edge servers, caching proxies, link checkers

Padrão

HEAD /resource HTTP/1.1

Estrutura central

HEAD /resource

Slots de substituição

resource: URI path string identifying the target resource

Colocados típicos

If-Modified-Since header
If-None-Match header
ETag
Content-Length
Content-Type
304 Not Modified response

Substituições comuns

GET request: transfers full body
wastes bandwidth when only metadata is needed OPTIONS request: describes communication options
used for CORS preflight rather than resource inspection Conditional GET with If-Modified-Since: achieves similar cache validation but still transfers body on 200

Erros comuns

Expecting a response body: HEAD returns headers only, so code that reads response.content or response.text gets empty data — must read response.headers instead Using HEAD for state changes: HEAD must be safe and idempotent; servers must not perform side effects, so use POST/PUT/PATCH for modifications Ignoring status codes: HEAD still returns 200/404/500, and code that only inspects headers may miss failure states Assuming HEAD is auto-routed: many frameworks require an explicit HEAD handler separate from GET, unlike Flask which derives it automatically Not handling 405 Method Not Allowed: some servers don't implement HEAD and return 405, requiring fallback to a lightweight GET

Similar / contraste

GET: transfers the full response body alongside headers OPTIONS: describes communication options for a resource, primarily for CORS preflight TRACE: echoes the received request back for diagnostics, not for resource metadata

Interferências

Coming from REST frameworks (Flask/Django): may assume HEAD is auto-derived from GET — Express.js and FastAPI require explicit HEAD route registration Coming from browser fetch API: fetch(url, {method:'HEAD'}) returns an opaque response in some browsers where headers are inaccessible, unlike Node.js where headers are readable

Família do chunk

HTTP methods: GET
POST
PUT
DELETE
PATCH
HEAD
OPTIONS

Nuance

When NOT to use: when the actual resource content is needed (use GET), or when targeting servers known not to implement HEAD (fall back to ranged GET) Performance: saves full body transfer, critical for large resources, frequent polling, or bandwidth-constrained mobile clients Boundary conditions: some servers return headers that differ between HEAD and GET (e.g., Content-Length on HEAD but chunked encoding on GET), and HEAD is not safe to retry blindly if the server is non-conforming

Efeito pragmático

Enables bandwidth-efficient cache validation, broken-link detection, and resource metadata inspection without full content transfer, reducing network costs and improving perceived latency in polling-heavy workflows.

Dica de memória

HEAD request: like knocking on a door to check if anyone's home before walking in — you get the answer (headers) without entering the house (body).

Upgrade path

Conditional HEAD requests with If-None-Match / If-Modified-Since for cache validation pipelines

Frequência: MediumFormulaicidade: Semi-fixedPrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Short-term

Examples

import requests response = requests.head("https://api.example.com/users/42") if response.status_code == 200: last_modified = response.headers.get("Last-Modified") content_type = response.headers.get("Content-Type") print(f"User exists, last modified: {last_modified}, type: {content_type}") elif response.status_code == 404: print("User not found")

curl -I -H "If-Modified-Since: Wed, 21 Oct 2023 07:28:00 GMT" \ https://cdn.example.com/assets/logo.png # Returns 304 Not Modified if cache is fresh, 200 with new headers if changed

async function checkLinkHealth(url) { const response = await fetch(url, { method: "HEAD" }); return response.ok; } const isHealthy = await checkLinkHealth("https://example.com/page"); console.log(`Link status: ${isHealthy ? "reachable" : "broken"}`);