Content resources represent byte-oriented data and can support range-based features like resumable downloads and skip-ahead downloading when they mix in the Entity profile.
HEAD request will return the following response. The headers are explained in the table below.
|Content-Length||The number of bytes in the content.|
|Content-Type||The media-type of the content.|
Fetch the Content resource with a
GET request. The body of the response contains the content bytes. The resource provides a
Content-Disposition header indicating what a client should do with the content. See RFC 6266 for details.
A client can change the content’s bytes by sending a
PUT request with the new content. The resource may reject the operation if the payload is too large or of the wrong media type.
Content resources do not support the
A client can delete the Content resource by sending a
The Preflight profile mixin allows a client to validate content modification before sending a payload. The client must send
Content-Type as preflight headers.
Content resources can provide the Representation profile as a mixin so the client can receive the modified representation in the response of a
When a Content resource mixes in the Entity profile, it includes the Entity profile’s validation headers in fetch requests. These headers enable Entity’s Cache-Aware Fetch flow. These headers also enable range requests. The
Accept-Ranges: bytes header indicates that the resource can accept range requests.
The Entity mixin allows a Content resource to use Entity’s modification behaviours, including the option of preflighting operations based on validation headers:
A client can download a portion of the content using a range request. They are useful for resuming interrupted downloads, jumping to a midway point in the content or downloading the content in stages.
The client has two options for range requests, and a Content resource must support both. One option (Fail-Fast) fails the range request if the Entity validation headers do not match, and the other (Refetch) switches to downloading the entire content if the validations do not match. A range request depends on validators to ensure the content’s bytes are the same from the previous request.
For both options the client discovers the range and validator information with either a
HEAD request or an incomplete
GET request. The client then sends a
GET request with the byte range of the content they would like to receive in a
Range header. If the content range cannot be delivered, a
416 Requested Range Not Satisfiable is returned with the total number of available bytes in the
Content-Range header. This condition occurs when the client requests a content range that goes beyond the size of the content itself.
Fail-Fast gives the client an option to perform range requests without triggering a full download if the client changes. The client follows the Entity Cache-Aware Fetching flow with the additional
Range header as described above. If the content is the same, then the client receives a
206 Partial Content status and the partial payload defined in the range. If the content has changed, the client receives a
409 Conflict status. In this case, the client may choose to fetch the content without validation headers.
Refetch allows the client to automatically restart a download if the content has changed from a previous attempt, but without processing a
409 Conflict status code. The client sends the
ETag value, or
Last-Modified value if ETag is unavailable, in an
If-Match header; it can contain either value, but not both. This single header validates the content has not changed. If the content has changed, or if the validators are not strong then the full content is returned instead of the range. In this case, the resource responds as a Fetch Content request.
The HTTP/1.1 Range Request specification allows requests to specify multiple ranges in the
Range header, with the ranges delivered in a multipart-formatted response. However, the Content profile does not support these multiple range requests because they are complicated to support and increasingly-unnecessary given HTTP/2’s ability to parallelize requests. Clients that wish to fetch multiple parts should make multiple range requests and let HTTP/2 take care of the multiplexing.
HTTP/1.1 Message Syntax and Routing: RFC 7230
- Content-Length: section 3.3.2
HTTP/1.1 Semantics and Content: RFC 7231
Content-Disposition: RFC 6266
Conditional Requests: RFC 7232
Range Requests: RFC 7233
- Range: section 2.1
- Accept-Ranges: section 2.3
- If-Range: section 3.2
- 206 Partial Content: section 4.1
- Content-Range: section 4.2
- 416 Range Not Satisfiable: section 4.4
Copyright © 2019 Matt Bishop
This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.