Content Profile

profile: <https://level3.rest/profiles/content>

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.

Discovery

A HEAD request will return the following response. The headers are explained in the table below.

Header	Value
accept-ranges	`bytes` means the resource accepts range requests. `none` means this resource cannot accept range requests, or the resource accepts range requests, but the current Entity validators are not strong.
content-length	The number of bytes in the content.
content-type	The media-type of the content.
content-disposition	`inline` or `attachment; filename="<filename>"`. See RFC 6266 for possible disposition statements.

Fetch 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.

Change Content

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 PATCH or POST operations.

Delete Content

A client can delete the Content resource by sending a DELETE request.

Mixins

Preflight Mixin

The Preflight profile mixin allows a client to validate content modification before sending a payload. The client must send content-length and content-type as preflight headers.

Representation Mixin

Content resources can provide the Representation profile as a mixin so the client can receive the modified representation in the response of a PUT operation.

Entity Mixin

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:

Range Requests

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

Fail-Fast gives the client an option to perform range requests without triggering a full download if the content changed. The client follows the Entity Cache-Aware Fetching flow with the additional range header. 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

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-range 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.

No Multipart Ranges

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.