You’re reading the English version of this content since no translation exists yet for this locale. Help us translate this article!
HTTP range requests allow to send only a portion of an HTTP message from a server to a client. Partial requests are useful for large media or downloading files with pause and resume functions, for example.
Checking if a server supports partial requests
curl -I http://i.imgur.com/z4d4kWk.jpg HTTP/1.1 200 OK ... Accept-Ranges: bytes Content-Length: 146515
In this response,
Accept-Ranges: bytes indicates that bytes can be used as unit to define a range. Here the
Content-Length header is also useful as it indicates the full size of the image to retrieve.
If sites omit the
Accept-Ranges header, they likely don't support partial requests. Some sites also explicitly send "
none" as a value, indicating no support. In some apps, download managers disable their pause buttons in that case.
curl -I https://www.youtube.com/watch?v=EwTZ2xpQwpA HTTP/1.1 200 OK ... Accept-Ranges: none
Requesting a specific range from a server
If the server supports range requests, you can issue such a request by using the
Range header. It indicates the part(s) of a document that the server should return.
Single part ranges
We can request a single range from a resource. Again, we can test a request by using cURL. The "
-H" option will append a header line to the request, which in this case is the
Range header requesting the first 1024 bytes.
curl http://i.imgur.com/z4d4kWk.jpg -i -H "Range: bytes=0-1023"
The issued request looks like this:
GET /z4d4kWk.jpg HTTP/1.1 Host: i.imgur.com Range: bytes=0-1023
The server responses with the
Partial Content status:
HTTP/1.1 206 Partial Content Content-Range: bytes 0-1023/146515 Content-Length: 1024 ... (binary content)
Content-Length header now indicates the size of the requested range (and not the full size of the image). The
Content-Range response header indicates where in the full resource this partial message belongs.
Range header also allows you to get multiple ranges at once in a multipart document. The ranges are separated by a comma.
curl http://www.example.com -i -H "Range: bytes=0-50, 100-150"
The server responses with the
Partial Content status and a
: multipart/byteranges; boundary=3d6b6a416f9b5 header, indicating that a multipart byterange follows. Each part contains its own
Content-Range fields and the required boundary parameter specifies the boundary string used to separate each body-part.
HTTP/1.1 206 Partial Content Content-Type: multipart/byteranges; boundary=3d6b6a416f9b5 Content-Length: 282 --3d6b6a416f9b5 Content-Type: text/html Content-Range: bytes 0-50/1270 <!doctype html> <html> <head> <title>Example Do --3d6b6a416f9b5 Content-Type: text/html Content-Range: bytes 100-150/1270 eta http-equiv="Content-type" content="text/html; c --3d6b6a416f9b5--
Conditional range requests
When resuming to request more parts of a resource, you need to guarantee that the stored resource has not been modified since the last fragment has been received.
If-Range HTTP request header makes a range request conditional: if the condition is fulfilled, the range request will be issued and the server sends back a
Partial Content answer with the appropriate body. If the condition is not fulfilled, the full resource is sent back, with a
OK status. This header can be used either with a
Last-Modified validator, or with an
ETag, but not with both.
If-Range: Wed, 21 Oct 2015 07:28:00 GMT
Partial request responses
There are three relevant statuses, when working with range requests:
- In case of a successful range request, the
Partial Contentstatus is sent back from a server.
- In case of a range request that is out of bounds (range values overlap the extent of the resource), the server responds with a
Requested Range Not Satisfiablestatus.
- In case of no support of range requests, the
OKstatus is sent back from a server.
Comparison to chunked
Transfer-Encoding header allows chunked encoding, which is useful when larger amounts of data are sent to the client and the total size of the response is not known until the request has been fully processed. The server sends data to the client straight away without buffering the response or determining the exact length, which leads to improved latency. Range requests and chunking are compatible and can be used with or without each other.