HTTP-If-None-Match-Header

Typ

Der If-None-Match-Header ist ein Conditional-Request-Header, der eine Anfrage nur ausführt, wenn die Ressource nicht dem angegebenen ETag entspricht.

Syntax

Der Header enthält einen oder mehrere ETags oder das Wildcard-Symbol für Cache-Validierung und Duplikat-Prevention.

http 
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
If-None-Match: W/"0815", "v2", "xyz"

Direktiven

Der If-None-Match-Header akzeptiert spezifische ETags (Strong oder Weak Validators) oder das Wildcard-Symbol für Ressourcen-Existenz-Prüfung.

etag-value
Ein oder mehrere ETag-Werte (Strong oder Weak), die NICHT mit dem aktuellen ETag matchen dürfen.
wildcard
Das Symbol * matcht jede existierende Ressource und verhindert die Erstellung bei bereits vorhandener Ressource.
weak-etag
Weak ETags (Präfix W/) erlauben semantische Äquivalenz statt byte-genauer Gleichheit.

Beispiele

Die folgenden Beispiele zeigen typische Anwendungsfälle für Cache-Validierung, Duplikat-Prevention bei POST-Requests und effiziente Bandbreiten-Nutzung.

Cache-Revalidierung mit If-None-Match

Ein Client validiert seinen Cache mit dem ETag und erhält 304 Not Modified bei unveränderter Ressource.

http 
GET /api/v1/products/12345 HTTP/1.1
Host: api.example.com
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response bei unveränderter Ressource:

http 
HTTP/1.1 304 Not Modified
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Cache-Control: max-age=3600

Response bei modifizierter Ressource:

http 
HTTP/1.1 200 OK
ETag: "a7f3b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9"
Content-Type: application/json

{
  "id": "12345",
  "name": "Premium Widget",
  "price": 149.99
}

Idempotente POST-Requests mit Duplikat-Prevention

Ein Client verhindert doppelte Resource-Erstellung durch If-None-Match mit Wildcard-Symbol.

http 
POST /api/v1/orders HTTP/1.1
Host: api.example.com
If-None-Match: *
Content-Type: application/json
Idempotency-Key: 7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "productId": "prod_789",
  "quantity": 2
}

Response bei erfolgreicher Erstellung:

http 
HTTP/1.1 201 Created
Location: /api/v1/orders/98765
ETag: "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1"
Content-Type: application/json

{
  "id": "98765",
  "status": "created"
}

Response bei bereits existierender Ressource:

http 
HTTP/1.1 412 Precondition Failed
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/duplicate-resource",
  "title": "Resource already exists",
  "status": 412,
  "detail": "Order with this idempotency key already exists"
}

Weak ETag Validierung für Content Negotiation

Ein Client akzeptiert semantisch äquivalente Repräsentationen durch Weak ETag Matching.

http 
GET /api/v1/reports/quarterly-2025-q3 HTTP/1.1
Host: api.example.com
If-None-Match: W/"q3-2025-v1", W/"q3-2025-v2"
Accept: application/pdf, application/json

ETag-Validierung-Flow

Der If-None-Match-Header ermöglicht effiziente Cache-Validierung und verhindert Ressourcen-Duplikate durch ETag-Vergleich.

plantuml 
@startuml
!theme plain
skinparam BoxPadding 20
skinparam ParticipantPadding 20

participant "Client" as client
participant "API\nServer" as api
database "Database" as db
participant "Cache" as cache

client -> api: GET /api/products/123
api -> db: SELECT * FROM products\nWHERE id = 123
db --> api: Product Data
api -> api: Calculate ETag:\nMD5(JSON)
api --> client: 200 OK\nETag: "abc123"\n[Product JSON]

client -> cache: Store with ETag "abc123"

note over client: Client cached\nproduct with ETag

client -> api: GET /api/products/123\nIf-None-Match: "abc123"
api -> db: SELECT * FROM products\nWHERE id = 123
db --> api: Product Data
api -> api: Calculate ETag:\nMD5(JSON) = "abc123"
api -> api: ETag matches:\nNO changes

api --> client: 304 Not Modified\nETag: "abc123"
client -> cache: Use cached version

note over client: Bandbreite gespart

== Alternative: Ressource wurde modifiziert ==

client -> api: GET /api/products/123\nIf-None-Match: "abc123"
api -> db: SELECT * FROM products\nWHERE id = 123
db --> api: Product Data (modified)
api -> api: Calculate ETag:\nMD5(JSON) = "xyz789"
api -> api: ETag differs:\nSend new version

api --> client: 200 OK\nETag: "xyz789"\n[Updated Product JSON]
client -> cache: Update cache with new ETag
@enduml

Vorteile für die Systemarchitektur

  • Effiziente Cache-Validierung mit 304-Not-Modified-Responses
  • Duplikat-Prevention bei POST-Requests durch Wildcard-Matching
  • Weak-ETag-Unterstützung für Content-Negotiation-Szenarien
  • Kombinierbar mit If-Modified-Since für robuste Cache-Strategie
  • Native Unterstützung in HTTP-Caches (CDN, Reverse Proxies)

Spezifikation

RFC 9110 (HTTP Semantics) definiert den If-None-Match-Header als Conditional-Request-Mechanismus für ETag-basierte Cache-Validierung und Ressourcen-Existenz-Prüfung.

Weitere Spezifikationen

ETag Header, HTTP Status 304 - Not Modified, If-Match Header