Upload-Length

The unofficial Upload-Length header field declares the total size of the representation a resumable upload will transfer, letting the server validate limits and allocate storage before the bytes arrive.

Table of Contents

Usage
Values
Example
See also

Usage

The Upload-Length header field states the full representation size in bytes on the request creating an upload resource, whichever content-bearing method creates it, or on a later PATCH append, once the client knows the size. A server reading a declared length beyond the max-size limit from Upload-Limit declines to create the upload resource before any content transfers, instead of discovering the overrun midway.

The length interacts with two other size signals. A request marked final through Upload-Complete implies the total size from Upload-Offset plus Content-Length. When both the implied and the declared lengths appear in one request, the two numbers have to match, and a declared length stays fixed across every request touching the same upload resource. Conflicting numbers fail the request, with the inconsistent-upload-length problem type available to name the error.

A client streaming a source of unknown size leaves the header out and relies on the final Upload-Complete marker alone. The server then learns the total only when the last chunk arrives.

The field also travels in responses. A successful offset retrieval against the upload resource carries Upload-Length whenever the server knows the total, so a resuming client recovers the declared size along with the offset. A client abandoning the transfer cancels the upload with a DELETE request against the upload resource.

Values

The value is a Structured Fields Item holding a non-negative integer: the size of the complete representation in bytes.

Example

The example leaves out the Upload-Draft-Interop-Version handshake, which 104 covers.

A client creates an upload resource for a 6553600 byte video and declares the size up front. The first chunk carries the opening bytes, and the server checks the declared total against its limits before storing anything.

Request

POST /videos HTTP/1.1
Host: www.example.re
Upload-Length: 6553600
Upload-Complete: ?0
Content-Type: video/mp4
Content-Length: 5242880

[first 5242880 bytes]

Response

HTTP/1.1 104 Upload Resumption Supported
Location: https://www.example.re/uploads/b3k2pp5k7z
Upload-Limit: max-size=1073741824

The final response to the creation request repeats the resource address once the first chunk is processed.