HTTP-If-Range-Header

Typ

Der If-Range-Header ist ein Conditional-Request-Header, der Range-Requests nur bei unveränderter Ressource ausführt und andernfalls die vollständige Ressource zurückgibt.

Syntax

Der Header enthält entweder einen ETag oder einen HTTP-Date-Timestamp zur Validierung der Ressourcenversion.

http 
If-Range: "33a64df551425fcc55e4d42a148795d9f25f89d4"
If-Range: Wed, 21 Oct 2025 07:28:00 GMT

Direktiven

Der If-Range-Header akzeptiert entweder einen ETag (Strong Validator bevorzugt) oder einen HTTP-Date-Wert für Ressourcenvalidierung.

etag-value
Ein Strong ETag, der mit dem aktuellen Ressourcen-ETag übereinstimmen muss (Weak ETags werden ignoriert).
http-date
Ein RFC 5322-konformer Zeitstempel, der mit dem Last-Modified-Wert der Ressource verglichen wird.

Beispiele

Die folgenden Beispiele zeigen typische Anwendungsfälle für Download-Resumption, Partial-Content-Validierung und Bandbreiten-Optimierung.

Download-Resumption mit ETag-Validierung

Ein Client setzt einen unterbrochenen Download fort und validiert die Ressource via ETag.

http 
GET /api/v1/exports/large-dataset.csv HTTP/1.1
Host: api.example.com
Range: bytes=5242880-
If-Range: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response bei unveränderter Ressource (Partial Content):

http 
HTTP/1.1 206 Partial Content
Content-Type: text/csv
Content-Range: bytes 5242880-10485760/10485761
ETag: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
Content-Length: 5242881

[Partial CSV data from byte 5242880...]

Response bei modifizierter Ressource (Full Content):

http 
HTTP/1.1 200 OK
Content-Type: text/csv
ETag: "a7f3b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"
Content-Length: 10485761

[Complete CSV data from beginning...]

Video-Streaming mit Zeitstempel-Validierung

Ein Video-Player lädt Partial Content und validiert die Ressource via Last-Modified-Timestamp.

http 
GET /api/v1/media/video-12345.mp4 HTTP/1.1
Host: media.example.com
Range: bytes=1048576-2097152
If-Range: Sat, 15 Sep 2025 10:00:00 GMT
Accept: video/mp4

API-Export mit Chunk-basiertem Download

Ein Client lädt große API-Export-Dateien in Chunks und validiert jeden Chunk-Request.

http 
GET /api/v1/reports/annual-2025.pdf HTTP/1.1
Host: api.example.com
Range: bytes=0-1048575
If-Range: "d3b07384d113edec49eaa6238ad5ff00"
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

If-Range-Validation-Flow

Der If-Range-Header optimiert Partial-Content-Requests durch automatische Fallback-Logik bei Ressourcen-Änderungen.

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

participant "Client" as client
participant "API\nServer" as api
participant "Storage" as storage

client -> api: GET /api/exports/file.csv\nRange: bytes=0-1023
api -> storage: Read bytes 0-1023
storage --> api: Partial data
api --> client: 206 Partial Content\nETag: "abc123"\nContent-Range: bytes 0-1023/5000

note over client: Download interrupted\nat byte 1024

note over client: Client resumes\ndownload

client -> api: GET /api/exports/file.csv\nRange: bytes=1024-\nIf-Range: "abc123"
api -> storage: Check current ETag
storage --> api: Current ETag: "abc123"
api -> api: ETag matches:\nProceed with Range

api -> storage: Read bytes 1024-end
storage --> api: Partial data
api --> client: 206 Partial Content\nETag: "abc123"\nContent-Range: bytes 1024-4999/5000

note over client: Download completed

== Alternative: Ressource wurde modifiziert ==

client -> api: GET /api/exports/file.csv\nRange: bytes=1024-\nIf-Range: "abc123"
api -> storage: Check current ETag
storage --> api: Current ETag: "xyz789"\n(Resource changed)
api -> api: ETag differs:\nIgnore Range, send full

api -> storage: Read complete file
storage --> api: Full data
api --> client: 200 OK\nETag: "xyz789"\nContent-Length: 6000\n[Complete file]

note over client: Client receives\nfull updated file\ninstead of partial
@enduml

Vorteile für die Systemarchitektur

  • Automatische Fallback-Logik: 206 Partial bei Match, 200 Full bei Mismatch
  • Download-Resumption für große API-Exports und Media-Dateien
  • Verhindert korrupte Partial-Content-Reassembly bei Ressourcen-Änderungen
  • Kombinierbar mit Range-Header für Chunk-basierte Downloads
  • Unterstützung für Strong ETags und Last-Modified-Timestamps

Spezifikation

RFC 9110 (HTTP Semantics) definiert den If-Range-Header als Conditional-Request-Mechanismus für sichere Range-Requests mit automatischer Ressourcen-Validierung.

Weitere Spezifikationen

Range Header, ETag Header, Last-Modified Header