draft-ietf-httpbis-resumable-upload-13.txt   draft-ietf-httpbis-resumable-upload-latest.txt 
HTTP Working Group M. Kleidl, Ed. HTTP Working Group M. Kleidl, Ed.
Internet-Draft Transloadit Internet-Draft Transloadit
Intended status: Standards Track G. Zhang, Ed. Intended status: Standards Track G. Zhang, Ed.
Expires: April 9, 2027 Apple Inc. Expires: May 7, 2027 Apple Inc.
L. Pardue, Ed. L. Pardue, Ed.
Cloudflare Apple
October 06, 2026 November 03, 2026
Resumable Uploads for HTTP Resumable Uploads for HTTP
draft-ietf-httpbis-resumable-upload-13 draft-ietf-httpbis-resumable-upload-latest
Abstract Abstract
HTTP data transfers can encounter interruption due to reasons such as HTTP data transfers can encounter interruption due to reasons such as
canceled requests or dropped connections. If the intended recipient canceled requests or dropped connections. If the intended recipient
can indicate how much of the data was processed prior to can indicate how much of the data was processed prior to
interruption, a sender can resume data transfer at that point instead interruption, a sender can resume data transfer at that point instead
of attempting to transfer all of the data again. HTTP range requests of attempting to transfer all of the data again. HTTP range requests
support this concept of resumable downloads from server to client. support this concept of resumable downloads from server to client.
This document describes a mechanism that supports resumable uploads This document describes a mechanism that supports resumable uploads
skipping to change at page 2, line 10 skipping to change at page 2, line 10
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 9, 2027. This Internet-Draft will expire on May 7, 2027.
Copyright Notice Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 5 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 5
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Example 1: Complete upload of representation data with 3.1. Example 1: Complete Upload of Representation Data with
known size . . . . . . . . . . . . . . . . . . . . . . . 6 Known Size . . . . . . . . . . . . . . . . . . . . . . . 6
3.2. Example 2: Upload as a series of parts . . . . . . . . . 8 3.2. Example 2: Upload as a Series of Parts . . . . . . . . . 8
4. Upload Resource . . . . . . . . . . . . . . . . . . . . . . . 10 4. Upload Resource . . . . . . . . . . . . . . . . . . . . . . . 11
4.1. State . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.1. Offset . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1.1. Offset . . . . . . . . . . . . . . . . . . . . . . . 11 4.1.1. Upload-Offset . . . . . . . . . . . . . . . . . . . . 12
4.1.2. Completeness . . . . . . . . . . . . . . . . . . . . 12 4.2. Completeness . . . . . . . . . . . . . . . . . . . . . . 12
4.1.3. Length . . . . . . . . . . . . . . . . . . . . . . . 12 4.2.1. Upload-Complete . . . . . . . . . . . . . . . . . . . 12
4.1.4. Limits . . . . . . . . . . . . . . . . . . . . . . . 13 4.3. Length . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2. Upload Creation . . . . . . . . . . . . . . . . . . . . . 16 4.3.1. Upload-Length . . . . . . . . . . . . . . . . . . . . 14
4.2.1. Client Behavior . . . . . . . . . . . . . . . . . . . 16 5. Upload Limits . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2.2. Server Behavior . . . . . . . . . . . . . . . . . . . 18 5.1. Upload-Limit . . . . . . . . . . . . . . . . . . . . . . 14
4.2.3. Examples . . . . . . . . . . . . . . . . . . . . . . 19 5.1.1. max-size . . . . . . . . . . . . . . . . . . . . . . 15
4.3. Offset Retrieval . . . . . . . . . . . . . . . . . . . . 21 5.1.2. min-size . . . . . . . . . . . . . . . . . . . . . . 15
4.3.1. Client Behavior . . . . . . . . . . . . . . . . . . . 21 5.1.3. max-append-size . . . . . . . . . . . . . . . . . . . 15
4.3.2. Server Behavior . . . . . . . . . . . . . . . . . . . 22 5.1.4. min-append-size . . . . . . . . . . . . . . . . . . . 16
4.3.3. Examples . . . . . . . . . . . . . . . . . . . . . . 22 5.1.5. max-age . . . . . . . . . . . . . . . . . . . . . . . 16
4.4. Upload Append . . . . . . . . . . . . . . . . . . . . . . 23 5.2. Use with OPTIONS . . . . . . . . . . . . . . . . . . . . 16
4.4.1. Client Behavior . . . . . . . . . . . . . . . . . . . 23 5.3. Limit Changes . . . . . . . . . . . . . . . . . . . . . . 17
4.4.2. Server Behavior . . . . . . . . . . . . . . . . . . . 24 5.4. Limit Violations . . . . . . . . . . . . . . . . . . . . 17
4.4.3. Examples . . . . . . . . . . . . . . . . . . . . . . 25 6. Upload Creation . . . . . . . . . . . . . . . . . . . . . . . 18
6.1. Client Behavior . . . . . . . . . . . . . . . . . . . . . 18
4.5. Upload Cancellation . . . . . . . . . . . . . . . . . . . 26 6.2. Server Behavior . . . . . . . . . . . . . . . . . . . . . 19
4.5.1. Client Behavior . . . . . . . . . . . . . . . . . . . 26 6.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 21
4.5.2. Server Behavior . . . . . . . . . . . . . . . . . . . 27 7. Offset Retrieval . . . . . . . . . . . . . . . . . . . . . . 23
4.5.3. Example . . . . . . . . . . . . . . . . . . . . . . . 27 7.1. Client Behavior . . . . . . . . . . . . . . . . . . . . . 23
4.6. Concurrency . . . . . . . . . . . . . . . . . . . . . . . 27 7.2. Server Behavior . . . . . . . . . . . . . . . . . . . . . 23
4.7. Retry . . . . . . . . . . . . . . . . . . . . . . . . . . 28 7.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 24
5. Status Code 104 (Upload Resumption Supported) . . . . . . . . 29 8. Upload Append . . . . . . . . . . . . . . . . . . . . . . . . 24
6. Media Type application/partial-upload . . . . . . . . . . . . 30 8.1. Client Behavior . . . . . . . . . . . . . . . . . . . . . 24
7. Problem Types . . . . . . . . . . . . . . . . . . . . . . . . 30 8.2. Server Behavior . . . . . . . . . . . . . . . . . . . . . 25
7.1. Mismatching Offset . . . . . . . . . . . . . . . . . . . 30 8.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 27
7.2. Inconsistent Length . . . . . . . . . . . . . . . . . . . 31 9. Upload Cancellation . . . . . . . . . . . . . . . . . . . . . 28
8. Content Codings . . . . . . . . . . . . . . . . . . . . . . . 31 9.1. Client Behavior . . . . . . . . . . . . . . . . . . . . . 28
9. Transfer Codings . . . . . . . . . . . . . . . . . . . . . . 31 9.2. Server Behavior . . . . . . . . . . . . . . . . . . . . . 28
10. Upload Strategies . . . . . . . . . . . . . . . . . . . . . . 32 9.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 29
10.1. Optimistic Upload Creation . . . . . . . . . . . . . . . 32 10. Concurrency . . . . . . . . . . . . . . . . . . . . . . . . . 29
10.1.1. Upgrading To Resumable Uploads . . . . . . . . . . . 33 11. Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
10.2. Careful Upload Creation . . . . . . . . . . . . . . . . 33 12. Status Code 104 (Upload Resumption Supported) . . . . . . . . 31
11. Incremental Transfer, Processing and Forwarding . . . . . . . 34 13. Media Type application/partial-upload . . . . . . . . . . . . 31
12. Request Cancellation . . . . . . . . . . . . . . . . . . . . 34 14. Problem Types . . . . . . . . . . . . . . . . . . . . . . . . 31
13. Security Considerations . . . . . . . . . . . . . . . . . . . 35 14.1. Mismatching Offset . . . . . . . . . . . . . . . . . . . 31
13.1. Different Origins . . . . . . . . . . . . . . . . . . . 36 14.2. Inconsistent Length . . . . . . . . . . . . . . . . . . 32
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 15. Content Codings . . . . . . . . . . . . . . . . . . . . . . . 33
14.1. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . 36 16. Transfer Codings . . . . . . . . . . . . . . . . . . . . . . 33
14.2. HTTP Status Code . . . . . . . . . . . . . . . . . . . . 37 17. Upload Strategies . . . . . . . . . . . . . . . . . . . . . . 33
14.3. Media Type . . . . . . . . . . . . . . . . . . . . . . . 37 17.1. Optimistic Upload Creation . . . . . . . . . . . . . . . 33
14.4. HTTP Problem Types . . . . . . . . . . . . . . . . . . . 38 17.1.1. Upgrading to Resumable Uploads . . . . . . . . . . . 34
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 17.2. Careful Upload Creation . . . . . . . . . . . . . . . . 35
15.1. Normative References . . . . . . . . . . . . . . . . . . 39 18. Incremental Transfer, Processing, and Forwarding . . . . . . 35
15.2. Informative References . . . . . . . . . . . . . . . . . 40 19. Request Cancellation . . . . . . . . . . . . . . . . . . . . 36
Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 41 20. Security Considerations . . . . . . . . . . . . . . . . . . . 36
A.1. Since draft-ietf-httpbis-resumable-upload-12 . . . . . . 41 20.1. Upload Resource URIs . . . . . . . . . . . . . . . . . . 36
A.2. Since draft-ietf-httpbis-resumable-upload-11 . . . . . . 41 20.2. Untrusted Input . . . . . . . . . . . . . . . . . . . . 37
A.3. Since draft-ietf-httpbis-resumable-upload-10 . . . . . . 42 20.3. Content Scanning . . . . . . . . . . . . . . . . . . . . 37
A.4. Since draft-ietf-httpbis-resumable-upload-09 . . . . . . 42 20.4. Time-of-Check to Time-of-Use . . . . . . . . . . . . . . 37
A.5. Since draft-ietf-httpbis-resumable-upload-08 . . . . . . 42 20.5. Resource Exhaustion . . . . . . . . . . . . . . . . . . 37
A.6. Since draft-ietf-httpbis-resumable-upload-07 . . . . . . 43 20.6. Message Size Limits . . . . . . . . . . . . . . . . . . 37
A.7. Since draft-ietf-httpbis-resumable-upload-06 . . . . . . 43 20.7. Different Origins . . . . . . . . . . . . . . . . . . . 38
A.8. Since draft-ietf-httpbis-resumable-upload-05 . . . . . . 43 21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38
A.9. Since draft-ietf-httpbis-resumable-upload-04 . . . . . . 43 21.1. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . 38
A.10. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 43 21.2. HTTP Status Code . . . . . . . . . . . . . . . . . . . . 39
A.11. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 44 21.3. Media Type . . . . . . . . . . . . . . . . . . . . . . . 39
A.12. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 44 21.4. HTTP Problem Types . . . . . . . . . . . . . . . . . . . 40
A.13. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 44 22. References . . . . . . . . . . . . . . . . . . . . . . . . . 41
A.14. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 45 22.1. Normative References . . . . . . . . . . . . . . . . . . 41
A.15. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 45 22.2. Informative References . . . . . . . . . . . . . . . . . 42
A.16. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 45 Appendix A. Changes . . . . . . . . . . . . . . . . . . . . . . 42
Appendix B. Draft Version Identification . . . . . . . . . . . . 45 A.1. Since draft-ietf-httpbis-resumable-upload-15 . . . . . . 42
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 46 A.2. Since draft-ietf-httpbis-resumable-upload-14 . . . . . . 43
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 46 A.3. Since draft-ietf-httpbis-resumable-upload-13 . . . . . . 43
A.4. Since draft-ietf-httpbis-resumable-upload-12 . . . . . . 43
A.5. Since draft-ietf-httpbis-resumable-upload-11 . . . . . . 43
A.6. Since draft-ietf-httpbis-resumable-upload-10 . . . . . . 44
A.7. Since draft-ietf-httpbis-resumable-upload-09 . . . . . . 44
A.8. Since draft-ietf-httpbis-resumable-upload-08 . . . . . . 44
A.9. Since draft-ietf-httpbis-resumable-upload-07 . . . . . . 45
A.10. Since draft-ietf-httpbis-resumable-upload-06 . . . . . . 45
A.11. Since draft-ietf-httpbis-resumable-upload-05 . . . . . . 45
A.12. Since draft-ietf-httpbis-resumable-upload-04 . . . . . . 45
A.13. Since draft-ietf-httpbis-resumable-upload-03 . . . . . . 46
A.14. Since draft-ietf-httpbis-resumable-upload-02 . . . . . . 46
A.15. Since draft-ietf-httpbis-resumable-upload-01 . . . . . . 46
A.16. Since draft-ietf-httpbis-resumable-upload-00 . . . . . . 47
A.17. Since draft-tus-httpbis-resumable-uploads-protocol-02 . . 47
A.18. Since draft-tus-httpbis-resumable-uploads-protocol-01 . . 47
A.19. Since draft-tus-httpbis-resumable-uploads-protocol-00 . . 47
Appendix B. Draft Version Identification . . . . . . . . . . . . 47
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 48
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 49
1. Introduction 1. Introduction
HTTP data transfers can encounter interruption due to reasons such as HTTP data transfers can encounter interruption due to reasons such as
canceled requests or dropped connections. If the intended recipient canceled requests or dropped connections. If the intended recipient
can indicate how much of the data was processed prior to can indicate how much of the data was processed prior to
interruption, a sender can resume data transfer at that point instead interruption, a sender can resume data transfer at that point instead
of attempting to transfer all of the data again. HTTP range requests of attempting to transfer all of the data again. HTTP range requests
(see Section 14 of [HTTP]) support this concept of resumable data (see Section 14 of [HTTP]) support this concept of resumable data
transfers for downloads from server to client. While partial PUT is transfers for downloads from server to client. While partial PUT is
one method for uploading a partial representation (via Content-Range one method for uploading a partial representation (via the "Content-
in the request), there are caveats that affect its deployability; see Range" header field in the request), there are caveats that affect
Section 14.5 of [HTTP]. its deployability; see Section 14.5 of [HTTP].
Canceled upload request can be triggered for various reasons, Upload requests can be canceled for various reasons, including but
including but not limited to: not limited to:
explicit client cancellation: e.g., terminating a user-agent process explicit client cancellation: e.g., terminating a user-agent process
implicit client cancellation: e.g., terminating a tab, garbage implicit client cancellation: e.g., terminating a tab, garbage
collecting a process or internal error collecting a process, or an internal error
explicit server cancellation: e.g., scheduled maintenance explicit server cancellation: e.g., scheduled maintenance
implicit server cancellation: e.g., DoS mitigation or internal error implicit server cancellation: e.g., denial-of-service mitigation or
an internal error
Connections can be dropped due to a variety of network or transport Connections can be dropped due to a variety of network or transport
layer reasons triggered by endpoints or on-path elements. layer reasons triggered by endpoints or on-path elements.
This specification defines a new mechanism for resumable uploads from This specification defines a new mechanism for resumable uploads from
client to server that can seamlessly fall back to conventional client to server that can seamlessly fall back to conventional
uploads. When an upload is interrupted, clients can send subsequent uploads. When an upload is interrupted, clients can send subsequent
requests to query the server state and use this information to send requests to query the server state and use this information to send
the remaining representation data. Alternatively, they can cancel the remaining representation data. Alternatively, they can cancel
the upload entirely. Unlike ranged downloads, this protocol does not the upload entirely. Unlike ranged downloads, this protocol does not
support transferring an upload as multiple requests in parallel. support transferring an upload as multiple requests in parallel.
Utilizing resumable uploads, applications can recover from unintended With resumable uploads, applications can recover from unintended
interruptions, but also interrupt an upload on purpose to later interruptions. They can also interrupt an upload on purpose and
resume it, for example, when a user wants to pause an upload, the resume it later, for example, when a user wants to pause the upload,
device's network connectivity changes, or bandwidth should be saved the device's network connectivity changes, or bandwidth is needed for
for higher priority tasks. higher-priority tasks.
The document introduces the concept of an upload resource to This document introduces the concept of an upload resource to
facilitate resumable uploads (Section 4) and defines new header facilitate resumable uploads (Section 4). It defines new header
fields to communicate the state of the upload (Section 4.1), the fields to communicate the state of the upload (Section 4.1.1,
status code "104 (Upload Resumption Supported)" to indicate the Section 4.2.1, Section 4.3.1, and Section 5.1) and the "104 (Upload
resource's support for resumable uploads (Section 5), and the Resumption Supported)" status code to indicate the resource's support
for resumable uploads (Section 12). It also defines the
"application/partial-upload" media type to label partial "application/partial-upload" media type to label partial
representation data when resuming an upload (Section 6). representation data when resuming an upload (Section 13).
2. Conventions and Definitions 2. Conventions and Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
Some examples in this document contain long lines that may be folded, Some examples in this document contain long lines that are folded, as
as described in [RFC8792]. described in [RFC8792].
The terms Structured Header, Item, Dictionary, String, Integer, and This document uses the following terminology from Section 3 of
Boolean are imported from [STRUCTURED-FIELDS]. [STRUCTURED-FIELDS] to specify syntax and parsing: Item, Dictionary,
Integer, and Boolean.
The terms "representation", "representation data", "representation This document uses the following terms from Section 3 of [HTTP]:
metadata", "content", "client" and "server" are from Section 3 of "representation", "representation data", "representation metadata",
[HTTP]. "content", "client", and "server".
The term "URI" is used as defined in Section 4 of [HTTP]. This document uses the term "URI" as defined in [URI].
The term "patch document" is taken from [PATCH]. This document uses the term "patch document" from [PATCH].
An _upload resource_ is a temporary resource on the server that An _upload resource_ is a temporary resource on the server that
facilitates the resumable upload of one representation (Section 4). facilitates the resumable upload of one representation (Section 4).
A _104 interim response_ is an interim response with the "104 (Upload
Resumption Supported)" status code (Section 12).
3. Overview 3. Overview
Resumable uploads are supported in HTTP through use of a temporary Resumable uploads are supported in HTTP by a temporary resource, an
resource, an _upload resource_ (Section 4), that is separate from the _upload resource_ (Section 4), that is separate from the resource
resource being uploaded to and specific to that upload. By being uploaded to and specific to that upload. By interacting with
interacting with the upload resource, a client can retrieve the the upload resource, a client can retrieve the current offset of the
current offset of the upload (Section 4.3), append to the upload upload (Section 7), append to the upload (Section 8), and cancel the
(Section 4.4), and cancel the upload (Section 4.5). upload (Section 9).
The remainder of this section uses examples to illustrate different The remainder of this section uses examples to illustrate different
interactions with the upload resource. HTTP message exchanges, and interactions with the upload resource. HTTP message exchanges, and
thereby resumable uploads, use representation data (see Section 8.1 thereby resumable uploads, use representation data (see Section 8.1
of [HTTP]). This means that resumable uploads can be used with many of [HTTP]). This means that resumable uploads can be used with many
forms of content, such as static files, in-memory buffers, data from forms of content, such as static files, in-memory buffers, data from
streaming sources, or on-demand generated data. Examples are purely streaming sources, or on-demand generated data. Examples are purely
illustrative and non-normative. Implementations of this protocol are illustrative and non-normative. Implementations follow the normative
expected to follow normative requirements defined in other sections, requirements in the other sections and the security considerations in
together with applying security considerations presented in Section 20.
Section 13.
3.1. Example 1: Complete upload of representation data with known size 3.1. Example 1: Complete Upload of Representation Data with Known Size
In this example, the client first attempts to upload representation In this example, the client first attempts to upload representation
data with a known size in a single HTTP request to the resource at data with a known size in a single HTTP request to the resource at
"/project/123/files". An interruption occurs and the client then "/project/123/files". An interruption occurs and the client then
attempts to resume the upload using subsequent HTTP requests to the attempts to resume the upload using subsequent HTTP requests to the
upload resource at "/uploads/abc". upload resource at "/uploads/abc".
1) The client notifies the server that it wants to begin an upload 1) The client notifies the server that it wants to begin an upload
(Section 4.2). The server reserves the required resources to accept (Section 6). The server reserves the required resources to accept
the upload from the client and then sends an interim response to the the upload from the client and then sends an interim response to the
client, signaling support for resumable uploads and the upload client, signaling support for resumable uploads and the upload
resource's URI via the Location header field (Section 10.2.2 of resource's URI via the "Location" header field (Section 10.2.2 of
[HTTP]). The client can start sending the representation data in the [HTTP]). The client can start sending the representation data in the
request content immediately after the request header section. request content immediately after the request header section.
Alternatively, it could also await the acknowledgment in the form of Alternatively, it can wait for the interim response first.
the interim response.
Client Server Client Server
| | | |
| POST /project/123/files | | POST /project/123/files |
| Upload-Complete: ?1 | | Upload-Complete: ?1 |
| | | |
| [representation] | | [representation] |
|------------------------------------------->| |------------------------------------------->|
| | | |
| | Reserve resources | | Reserve resources
skipping to change at page 6, line 46 skipping to change at page 7, line 28
| | | |
| 104 Upload Resumption Supported | | 104 Upload Resumption Supported |
| Location: /uploads/abc | | Location: /uploads/abc |
|<-------------------------------------------| |<-------------------------------------------|
| | | |
X--------------Flow Interrupted--------------X X--------------Flow Interrupted--------------X
Figure 1: Upload Creation Figure 1: Upload Creation
2) If the connection to the server is interrupted, the client might 2) If the connection to the server is interrupted, the client might
want to resume the upload. However, before this is possible the want to resume the upload. However, before this is possible, the
client needs to know the amount of representation data that the client needs to know the amount of representation data that the
server processed before the interruption. It does so by retrieving server processed before the interruption. It does so by retrieving
the offset (Section 4.3) from the upload resource. the offset (Section 7) from the upload resource.
Client Server Client Server
| | | |
| HEAD /uploads/abc | | HEAD /uploads/abc |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 204 No Content | | 204 No Content |
| Upload-Offset: X | | Upload-Offset: X |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
Figure 2: Offset Retrieval Figure 2: Offset Retrieval
3) The client can resume the upload by sending the remaining 3) The client can resume the upload by sending the remaining
representation data to the upload resource (Section 4.4), appending representation data to the upload resource (Section 8), appending to
to the already stored representation data in the upload using the the already stored representation data in the upload using the
"application/partial-upload" media type. The "Upload-Offset" value "application/partial-upload" media type. The "Upload-Offset" header
is included to ensure that the client and server agree on the offset field is included to ensure that the client and server agree on the
that the upload resumes from. Once the remaining representation data offset that the upload resumes from. Once the remaining
is transferred, the server processes the entire representation and representation data is transferred, the server processes the entire
responds with whatever the initial request to "/project/123/files" representation and responds with whatever the initial request to
would have produced if it had not been interrupted, e.g., a "200 "/project/123/files" would have produced if it had not been
(OK)" response. interrupted, e.g., a "201 (Created)" response.
Client Server Client Server
| | | |
| PATCH /uploads/abc | | PATCH /uploads/abc |
| Upload-Complete: ?1 | | Upload-Complete: ?1 |
| Upload-Offset: X | | Upload-Offset: X |
| Content-Type: application/partial-upload | | Content-Type: application/partial-upload |
| | | |
| [representation from offset X] | | [representation from offset X] |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 200 OK | | 201 Created |
| Upload-Complete: ?1 |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
Figure 3: Upload Append Figure 3: Upload Append
4) If the client is not interested in completing the upload, it can 4) If the client is not interested in completing the upload, it can
instruct the server to delete the upload resource and all associated cancel the upload (Section 9). The server can then release the
representation data (Section 4.5). upload resource and any associated representation data.
Client Server Client Server
| | | |
| DELETE /uploads/abc | | DELETE /uploads/abc |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 204 No Content | | 204 No Content |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
Figure 4: Upload Cancellation Figure 4: Upload Cancellation
3.2. Example 2: Upload as a series of parts 3.2. Example 2: Upload as a Series of Parts
In some cases, clients might prefer to upload a representation as a In some cases, clients might prefer to upload a representation as a
series of parts sent serially across multiple HTTP messages. One use series of parts sent serially across multiple HTTP messages. One use
case is to overcome server limits on HTTP message content size. case is to overcome server limits on HTTP message content size.
Another use case is where the client does not know the final size of Another use case is where the client does not know the final size of
the representation data, such as when the data originates from a the representation data, such as when the data originates from a
streaming source. streaming source.
This example shows how the client, communicating with a resource This example shows how the client, communicating with a resource
known to support resumable upload, can upload parts of a known to support resumable uploads, can upload parts of a
representation incrementally. representation incrementally.
1) The client is aware that the targeted resource supports resumable 1) The client is aware that the target resource supports resumable
uploads and therefore starts the upload with the "Upload-Complete" uploads and therefore starts the upload with the "Upload-Complete"
field value set to false and the first part of the representation. header field set to false and the first part of the representation.
Client Server Client Server
| | | |
| POST /project/123/files | | POST /project/123/files |
| Upload-Complete: ?0 | | Upload-Complete: ?0 |
| | | |
| [partial representation] | | [partial representation] |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 201 Created | | 201 Created |
| Location: /uploads/abc | | Location: /uploads/abc |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
Figure 5: Upload creation with partial representation data Figure 5: Upload Creation with Partial Representation Data
2) Next, intermediate parts are appended (Section 4.4) with the 2) Next, intermediate parts are appended (Section 8) with the
"Upload-Complete" field value set to false, indicating that they are "Upload-Complete" header field set to false, indicating that they are
not the last part of the representation data. not the last part of the representation data.
Client Server Client Server
| | | |
| PATCH /uploads/abc | | PATCH /uploads/abc |
| Upload-Complete: ?0 | | Upload-Complete: ?0 |
| Upload-Offset: X | | Upload-Offset: X |
| Content-Type: application/partial-upload | | Content-Type: application/partial-upload |
| | | |
| [partial representation from offset X] | | [partial representation from offset X] |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 204 No Content | | 204 No Content |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
Figure 6: Appending partial representation data to upload Figure 6: Appending Partial Representation Data to Upload
3) If the connection was interrupted, the client might want to resume 3) If the connection was interrupted, the client might want to resume
the upload, similar to the previous example (Section 3.1). The the upload, similar to the previous example (Section 3.1). The
client retrieves the offset (Section 4.3) to learn the amount of client retrieves the offset (Section 7) to learn the amount of
representation data processed by the server and then continues representation data processed by the server and then continues
appending the remaining parts to the upload as in the previous step. appending the remaining parts to the upload as in the previous step.
Client Server Client Server
| | | |
| HEAD /uploads/abc | | HEAD /uploads/abc |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 204 No Content | | 204 No Content |
| Upload-Offset: Y | | Upload-Offset: Y |
skipping to change at page 9, line 48 skipping to change at page 10, line 26
| Upload-Offset: Y | | Upload-Offset: Y |
| Content-Type: application/partial-upload | | Content-Type: application/partial-upload |
| | | |
| [partial representation from offset Y] | | [partial representation from offset Y] |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 204 No Content | | 204 No Content |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
Figure 7: Resuming an interrupted upload Figure 7: Resuming an Interrupted Upload
4) The request to append the last part of the representation data has 4) The request to append the last part of the representation data has
an "Upload-Complete" field value set to true to indicate the complete the "Upload-Complete" header field set to true to indicate the
transfer. Once the remaining representation data is transferred, the complete transfer. Once the remaining representation data is
server processes the entire representation and responds with whatever transferred, the server processes the entire representation and
the initial request to "/project/123/files" would have produced if responds with whatever the initial request to "/project/123/files"
its representation had been fully transferred and processed, e.g., a would have produced if its representation had been fully transferred
"200 (OK)" response. and processed, e.g., a "201 (Created)" response.
Client Server Client Server
| | | |
| PATCH /uploads/abc | | PATCH /uploads/abc |
| Upload-Complete: ?1 | | Upload-Complete: ?1 |
| Upload-Offset: Z | | Upload-Offset: Z |
| Content-Type: application/partial-upload | | Content-Type: application/partial-upload |
| | | |
| [remaining representation from offset Z] | | [remaining representation from offset Z] |
|------------------------------------------------>| |------------------------------------------------>|
| | | |
| 200 OK | | 201 Created |
| Upload-Complete: ?1 |
|<------------------------------------------------| |<------------------------------------------------|
| | | |
Figure 8: Appending remaining representation data Figure 8: Appending Remaining Representation Data
4. Upload Resource 4. Upload Resource
A resumable upload is enabled through interaction with an upload A resumable upload is enabled through interaction with an upload
resource. When a resumable upload begins, the server is asked to resource. When a resumable upload begins, the server is asked to
create an upload resource through a request to another resource create an upload resource through a request to another resource
(Section 4.2). Using this upload resource, the client can query the (Section 6). Using this upload resource, the client can query the
upload progress (Section 4.3), append representation data upload progress (Section 7), append representation data (Section 8),
(Section 4.4), or cancel the upload (Section 4.5). The server is or cancel the upload (Section 9). The server is responsible for
responsible for persisting the state of the upload resource persisting the state of the upload resource (see below) and updating
(Section 4.1) and updating it as the upload progresses. it as the upload progresses. Limits (Section 5) can also apply to
the upload resource.
An upload resource is specific to the upload of one representation. An upload resource is specific to the upload of one representation.
For uploading multiple representations, multiple upload resources For uploading multiple representations, multiple upload resources
have to be used. have to be used.
The server can clean up an upload resource and make it inaccessible Server implementations need to decide how long to retain an upload
immediately after the upload is complete. However, keeping the resource after the upload is complete. The server can clean up the
upload resource available for a period of time after completion upload resource and make it inaccessible immediately. Keeping it
allows the client to verify the state of the upload if it did not longer lets a client that missed the final response verify the
receive the last response acknowledging the completion. upload's state, at a cost to the server.
Implementations are responsible for deciding if they retain the
resource and for what duration; they will need to consider the
resource costs required to do so.
An upload resource SHOULD be unique. Reuse of a URI for a different An upload resource SHOULD be unique. Reuse of a URI for a different
upload resource SHOULD be avoided in order to reduce the chance of upload resource SHOULD be avoided in order to reduce the chance of
misdirected or corrupted upload resources, as well as the potential misdirected or corrupted upload resources, as well as the potential
security issues described in Section 13. security issues described in Section 20.1.
4.1. State If the client receives a "3xx (Redirection)" response to a request to
the upload resource, and the response does not complete the upload
(Section 20.7), the client is not expected to follow the redirect,
because this protocol does not define how an upload continues at a
different URI.
The state of an upload consists of the following properties that are The state of an upload includes the following properties that are
tracked by the server. tracked by the server.
4.1.1. Offset 4.1. Offset
The offset is the number of bytes from the representation data that The offset is the number of bytes from the representation data that
have been processed, either during the creation of the upload have been processed, either during the creation of the upload
resource (Section 4.2) or by appending to it (Section 4.4). The resource (Section 6) or by appending to it (Section 8). The offset
offset is required when appending representation data (Section 4.4) is required when appending representation data to synchronize the
to synchronize the client and resource regarding the amount of client and resource regarding the amount of transferred
transferred representation data. representation data.
The offset reflects application-level processing for the upload. The offset reflects application-level processing for the upload.
Data may have been delivered and acknowledged at the transport layer Data might have been delivered and acknowledged at the transport
without yet being reflected in the offset. layer without yet being reflected in the offset.
The "Upload-Offset" request and response header field conveys the
offset. "Upload-Offset" is an Item Structured Header Field
([STRUCTURED-FIELDS]). Its value is a non-negative Integer
(Section 3.3.1 of [STRUCTURED-FIELDS]) and indicates the current
offset as viewed by the message sender. Other values MUST cause the
entire header field to be ignored.
The client obtains the current offset in multiple ways:
o The offset can be explicitly retrieved from the upload resource
(Section 4.3).
o Interim and final responses for creating the upload (Section 4.2)
or appending (Section 4.4) with a non-"2XX" status code and the
"Upload-Complete: ?0" header can include the "Upload-Offset"
header field.
o Final responses for appending representation data (Section 4.4)
with a "2XX" status code and the "Upload-Complete: ?0" header
acknowledge that the entire request content was received and the
offset increased by the length of the appended representation
data. An "Upload-Offset" header field's value MUST match this
inferred offset, if present.
Representation data processed by the upload resource cannot be Representation data processed by the upload resource cannot be
removed again and, therefore, the offset as seen by the client MUST removed again and, therefore, the offset as seen by the client MUST
NOT decrease. Clients can use this guarantee to free resources NOT decrease. Clients can use this guarantee to free resources
associated to transferred representation data, as no retransmission associated with transferred representation data, as no retransmission
of it will be necessary. If the server loses any part of the state, of it will be necessary. If the server loses any part of the state,
it MUST deactivate the upload resource and reject further interaction it MUST deactivate the upload resource and reject further interaction
with it. with it.
4.1.2. Completeness 4.1.1. Upload-Offset
An upload is incomplete until it is explicitly marked as completed by The "Upload-Offset" request and response header field is an Item
Structured Header Field of type Integer (Section 3.3.1 of
[STRUCTURED-FIELDS]). Its value is a non-negative Integer and
indicates the current offset, as viewed by the message sender. Other
values MUST cause the entire header field to be ignored. This
document does not define parameters for "Upload-Offset"; unknown
parameters MUST be ignored.
The client can learn the current offset in three ways:
o The offset can be explicitly retrieved from the upload resource
(Section 7).
o Interim responses for creating the upload (Section 6) or appending
(Section 8), and their final responses with a non-"2xx" status
code and the "Upload-Complete: ?0" header field, can include the
"Upload-Offset" header field.
o Final responses for appending representation data (Section 8) with
a "2xx (Successful)" status code and the "Upload-Complete: ?0"
header field acknowledge that the entire request content was
received and the offset increased by the length of the appended
representation data. If present, the "Upload-Offset" header field
value MUST match this inferred offset.
4.2. Completeness
An upload is incomplete until it is explicitly marked as complete by
the client or the server. After this point, no more representation the client or the server. After this point, no more representation
data can be appended. data can be appended.
The "Upload-Complete" request and response header field conveys the 4.2.1. Upload-Complete
completeness state. "Upload-Complete" is an Item Structured Header
Field ([STRUCTURED-FIELDS]). Its value is a Boolean (Section 3.3.6
of [STRUCTURED-FIELDS]) and indicates whether the upload is complete
or not. Other values MUST cause the entire header field to be
ignored.
An upload is marked as completed either when a request for creating The "Upload-Complete" request and response header field is an Item
the upload resource (Section 4.2) or appending to it (Section 4.4) Structured Header Field of type Boolean (Section 3.3.6 of
includes the "Upload-Complete" header field with a true value and the [STRUCTURED-FIELDS]). Other values MUST cause the entire header
field to be ignored. This document does not define parameters for
"Upload-Complete"; unknown parameters MUST be ignored.
An upload is marked as complete either when a request for creating
the upload resource (Section 6) or appending to it (Section 8)
includes the "Upload-Complete" header field set to true and the
request content was fully processed, or when a response includes the request content was fully processed, or when a response includes the
"Upload-Complete" header field with a true value. field set to true.
When used in an upload creation response (Section 4.2) or an upload In an upload creation response (Section 6) or an upload append
append response (Section 4.4), "Upload-Complete" signals whether the response (Section 8), the "Upload-Complete" header field indicates
response comes from the initial targeted resource. The value of true where the response comes from: true means the target resource of the
means that the semantics of the targeted resource apply, and the initial request, and false means the resumable upload protocol.
value of false means that the semantics of the resumable upload After a response with the "Upload-Complete" header field set to true,
protocol apply. The client SHOULD NOT perform upload resumption to the client SHOULD NOT resume the upload.
the upload resource after receiving a response with the "Upload-
Complete" field value set to true. Note that "Upload-Complete" can
be true even when the full representation data was not transmitted in
the case that the server decides to generate an early response when
processing the targeted resource. Also note that "Upload-Complete"
can be false in response to an invalid operation performed on a
completed upload.
4.1.3. Length Note that the "Upload-Complete" header field can be true even when
the full representation data was not transmitted, because the target
resource can generate an early response. Also note that it can be
false in response to an invalid request to a completed upload.
The length of the representation data might not be known when 4.3. Length
starting the transfer, for example, because the representation is
taken from a streaming source. The representation's length will,
however, be known at the latest when the client completes the upload
(Section 4.1.2).
Despite this, a client SHOULD communicate the representation's length The length is the number of bytes of the representation data. It
to the server as soon as it becomes known to aid with resource might not be known when starting the transfer, for example, because
management and facilitate early validation. There are two different the representation is taken from a streaming source. The length
ways for the client to indicate and for the server to discover the will, however, be known at the latest when the client completes the
representation's length from requests for creating the upload upload (Section 4.2).
resource (Section 4.2) or appending to it (Section 4.4):
1. If the request includes the "Upload-Complete" field value set to A client SHOULD communicate the representation's length to the server
as soon as it becomes known, without waiting for the upload to
complete. This aids resource management and allows early validation.
A request that creates the upload resource (Section 6) or appends to
it (Section 8) has two possible indicators of the length:
1. If the request includes the "Upload-Complete" header field set to
true, the request content is the remaining representation data. true, the request content is the remaining representation data.
The representation's length is then the sum of the current offset The representation's length is then the sum of the current offset
(Section 4.1.1) and the request content's length, which might be (Section 4.1) and the request content's length, which might be
announced in the "Content-Length" header field. announced in the "Content-Length" header field.
2. The request can include the "Upload-Length" header field defined 2. The request can include the "Upload-Length" header field defined
below. below.
The "Upload-Length" request and response header field is an Item
Structured Header Field ([STRUCTURED-FIELDS]). Its value is a non-
negative Integer (Section 3.3.1 of [STRUCTURED-FIELDS]) and indicates
the representation's length as a number of bytes. Other values MUST
cause the entire header field to be ignored.
If indicators (1) and (2) are both present in the same request, their If indicators (1) and (2) are both present in the same request, their
indicated lengths MUST match. The representation's length, if known, indicated lengths MUST match. The representation's length, if known,
MUST stay consistent across subsequent requests. A server can use MUST stay consistent across subsequent requests. A server SHOULD
the problem type [PROBLEM] of "https://iana.org/assignments/http- respond to a request with inconsistent length indicators with a "400
problem-types#inconsistent-upload-length" (Section 7.2) in responses (Bad Request)" status code, and can use the problem type [PROBLEM] of
to indicate inconsistent length indicators. "https://iana.org/assignments/http-problem-types#inconsistent-upload-
length" (Section 14.2) to indicate why.
The "Upload-Length" field can be used in response to an offset
retrieval; see Section 4.3.2.
Note that the length and offset values do not determine whether an Note that the length and offset values do not determine whether an
upload is complete. Instead, the client uses the "Upload-Complete" upload is complete. Instead, the client uses the "Upload-Complete"
(Section 4.1.2) header field to indicate that a request completes the header field (Section 4.2.1) to indicate that a request completes the
upload. The offset could match the length, but the upload can still upload. The offset could match the length, but the upload can still
be incomplete. be incomplete.
4.1.4. Limits 4.3.1. Upload-Length
A server MAY enforce one or multiple limits, which are communicated The "Upload-Length" request and response header field is an Item
to the client via the "Upload-Limit" response header field. "Upload- Structured Header Field of type Integer (Section 3.3.1 of
Limit" is a Dictionary Structured Header Field ([STRUCTURED-FIELDS]). [STRUCTURED-FIELDS]). Its value is a non-negative Integer and
Its value is a Dictionary (Section 3.2 of [STRUCTURED-FIELDS]). indicates the representation's length. Other values MUST cause the
Other values MUST cause the entire header field to be ignored. entire header field to be ignored. This document does not define
parameters for "Upload-Length"; unknown parameters MUST be ignored.
The following key-value pairs are defined: The "Upload-Length" field can be used in response to an offset
retrieval; see Section 7.2.
max-size: Specifies a maximum size for the representation data, 5. Upload Limits
counted in bytes. The server might not create an upload resource
if the representation's length (Section 4.1.3) deduced from the
upload creation request is larger than the maximum size. The
server might also deactivate the upload resource if the offset
(Section 4.1.1) exceeds the maximum size. The value is an
Integer.
min-size: Specifies a minimum size for the representation data, A server can limit an upload, for example, in its total size, in the
counted in bytes, for the server to offer resumable uploads. The size of each request, or in how long the upload resource remains
server might not create an upload resource if the representation's available. The server announces these limits to the client in the
length (Section 4.1.3) deduced from the upload creation request is "Upload-Limit" header field (Section 5.1), so the client can adhere
smaller than the minimum size or no length can be deduced at all. to them.
Resumable uploads impose additional overhead on the server, which
might not be acceptable for small representations. Requests with
representation data below this value might still be accepted by
the server, although without the ability to resume them. The
value is an Integer.
max-append-size: Specifies a maximum size counted in bytes for the A client usually learns the limits when the upload resource is
request content in a single upload append (Section 4.4) or upload created (Section 6). It can learn them before that through an
creation (Section 4.2) request. The server might reject requests "OPTIONS" request (Section 5.2).
exceeding this limit. A client that is aware of this limit MUST
NOT send larger upload append or upload creation requests. The
value is an Integer.
min-append-size: Specifies a minimum size counted in bytes for the 5.1. Upload-Limit
request content in a single upload append (Section 4.4) or upload
creation (Section 4.2) request. The server might reject requests
below this limit. A client that is aware of this limit MUST NOT
send smaller upload append or upload creation requests. The value
is an Integer. This limit does not apply to upload creation
requests with no content, or to requests completing the upload by
including the "Upload-Complete: ?1" header field.
max-age: Specifies the remaining lifetime of the upload resource in The "Upload-Limit" response header field is a Dictionary Structured
seconds counted from the generation of the response. After the Header Field (Section 3.2 of [STRUCTURED-FIELDS]). Other values MUST
resource's lifetime is reached, the server might make the upload cause the entire header field to be ignored. Receivers of the
resource inaccessible. The value is an Integer. "Upload-Limit" header field parse the Dictionary as described in
Section 4.2 of [STRUCTURED-FIELDS]. Where the Dictionary is
successfully parsed, this document places the following additional
requirements on Dictionary members.
Clients usually discover limits through the "Upload-Limit" header A member with an unknown key MUST be ignored. A member with a known
field when the upload resource is created (Section 4.2). Throughout key is only valid if it has the expected type and its value is within
the lifetime of the upload resource, these limits SHOULD NOT change the permitted range. Some members are related and their values can
in a way that causes failures for clients adhering to the initially specify a combined range, which has its own definition of validity.
discovered limits. If the client discovers that it cannot continue
the upload while adhering to the limits, it SHOULD stop the current Receiving an invalid member or members that specify an invalid
request immediately (Section 12) and cancel the upload (Section 4.5). combined range is an error. It MUST cause the entire "Upload-Limit"
header field to be ignored, or alternatively the complete HTTP
message MUST be treated as malformed.
This document does not define parameters for Dictionary member
values; unknown parameters MUST be ignored.
The following key-value pairs are defined.
5.1.1. max-size
The "max-size" limit specifies a maximum size, in bytes, for the
representation data. The value is an Integer greater than zero; a
value of zero would only permit empty uploads.
The server might not create an upload resource if the
representation's length (Section 4.3) deduced from the upload
creation request is larger than the maximum size. The server might
also deactivate the upload resource if the offset (Section 4.1)
exceeds the maximum size.
5.1.2. min-size
The "min-size" limit specifies a minimum size, in bytes, for the
representation data. The value is a non-negative Integer. It MUST
NOT be greater than the "max-size" value, if present.
The server might not create an upload resource if the
representation's length (Section 4.3) deduced from the upload
creation request is smaller than the minimum size or no length can be
deduced at all. Resumable uploads impose additional overhead on the
server, which might not be acceptable for small representations.
Requests with representation data below this value might still be
accepted by the server, although without the ability to resume them.
5.1.3. max-append-size
The "max-append-size" limit specifies a maximum size, in bytes, for
the request content in a single upload append (Section 8) or upload
creation (Section 6) request. The value is an Integer greater than
zero; a value of zero would only permit requests with no content.
The server might reject requests exceeding this limit. A client that
is aware of this limit MUST NOT send larger upload append or upload
creation requests.
5.1.4. min-append-size
The "min-append-size" limit specifies a minimum size, in bytes, for
the request content in a single upload append (Section 8) or upload
creation (Section 6) request. The value is a non-negative Integer.
It MUST NOT be greater than the "max-append-size" or "max-size"
values, if present. This limit does not apply to upload creation
requests with no content, or to requests completing the upload by
including the "Upload-Complete: ?1" header field.
The server might reject requests below this limit. A client that is
aware of this limit MUST NOT send smaller upload append or upload
creation requests.
5.1.5. max-age
The "max-age" limit specifies the remaining lifetime, in seconds, of
the upload resource, counted from the generation of the response.
The value is a non-negative Integer.
After the resource's lifetime is reached, the server might make the
upload resource inaccessible.
5.2. Use with OPTIONS
Before creating an upload resource, a client can send an "OPTIONS"
request to discover whether the resource supports resumable uploads
and to learn potential limits. The request does not include the
"Upload-Complete" header field; otherwise, it would be a request to
create an upload resource (Section 6).
When responding to such a request, if the target resource supports
the creation of a resumable upload resource (Section 6), the server
MUST include the "Upload-Limit" header field with the corresponding
limits in the response. If a server is configured such that all of
its resources support the creation of upload resources with identical
limits, it SHOULD include the "Upload-Limit" header field in response
to an "OPTIONS" request for the target "*" (if this target is
supported).
In an "OPTIONS" response, the presence of the "Upload-Limit" header
field signals support for resumable uploads, even when the server
applies no limits. An empty Dictionary is equivalent to omitting the
field (Section 3.2 of [STRUCTURED-FIELDS]), so it cannot carry this
signal. If the server does not apply any limits, it MUST send "min-
size=0".
To reduce the likelihood of failing requests, the limits announced in
an "OPTIONS" response SHOULD NOT be less restrictive than the limits
applied to an upload once the upload resource has been created,
unless the request to create an upload resource included additional
information that warrants different limits. For example, a server
might announce a general maximum size limit of 1 GB, but reduce it to
100 MB when the media type indicates an image.
5.3. Limit Changes
Throughout the lifetime of the upload resource, limits SHOULD NOT
change in a way that causes failures for clients adhering to the
initially discovered limits. If the client discovers that it cannot
continue the upload while adhering to the limits, it SHOULD stop the
current request immediately (Section 19) and cancel the upload
(Section 9).
The following recommendations for limit changes can minimize the risk The following recommendations for limit changes can minimize the risk
of causing upload failures: of causing upload failures:
o "max-size" and "max-append-size" SHOULD NOT decrease. o "max-size" and "max-append-size" SHOULD NOT decrease.
o "min-size" and "min-append-size" SHOULD NOT increase. o "min-size" and "min-append-size" SHOULD NOT increase.
o Between subsequent responses, the end of the upload resource's o Between subsequent responses, the end of the upload resource's
lifetime as implied by "max-age" SHOULD NOT decrease. lifetime as implied by "max-age" SHOULD NOT decrease.
Receivers of "Upload-Limit" parse the Dictionary as described in 5.4. Limit Violations
Section 4.2 of [STRUCTURED-FIELDS]. Where the Dictionary is
successfully parsed, this document places two additional requirements
on Dictionary members. First, a member with an unknown key MUST be
ignored. Second, a member with a known key but a value of unexpected
type MUST cause the entire "Upload-Limit" header field to be ignored,
or alternatively the complete HTTP message MUST be treated as
malformed.
When responding to an "OPTIONS" request without the "Upload-Complete"
header field, if the resource that is the target of the request
supports the creation of a resumable upload resource (Section 4.2),
the server MUST include the "Upload-Limit" header field with the
corresponding limits in the response. If a server is configured such
that all of its resources support the creation of upload resources
with identical limits, it SHOULD include the "Upload-Limit" header
field in response to an "OPTIONS" request for the target "*" (if this
target is supported). If the server does not apply any limits, it
MUST use "min-size=0" instead of an empty header value.
A client can use an "OPTIONS" request without the "Upload-Complete"
header field to discover whether the resource supports resumable
uploads and to learn potential limits before creating an upload
resource. To reduce the likelihood of failing requests, the limits
announced in an "OPTIONS" response SHOULD NOT be less restrictive
than the limits applied to an upload once the upload resource has
been created, unless the request to create an upload resource
included additional information that warrants different limits. For
example, a server might announce a general maximum size limit of 1
GB, but reduce it to 100 MB when the media type indicates an image.
When a request is rejected because limits were violated, the response When a request is rejected because limits were violated, the response
SHOULD include the "Upload-Limit" header field carrying all limits of SHOULD include the "Upload-Limit" header field carrying all limits of
the corresponding upload if possible. This might not be possible if the corresponding upload if possible. This might not be possible if
intermediaries enforce limits. intermediaries enforce limits.
Servers, including intermediaries, can (and often do) apply Servers, including intermediaries, can (and often do) apply
restrictions on the size of individual request message content. restrictions on the size of individual request message content.
There is no standard mechanism to communicate such existing size There is no standard mechanism to communicate such existing size
restriction. A server that implements one can respond with a "413 restriction. A server that implements one can respond with a "413
skipping to change at page 16, line 4 skipping to change at page 17, line 44
When a request is rejected because limits were violated, the response When a request is rejected because limits were violated, the response
SHOULD include the "Upload-Limit" header field carrying all limits of SHOULD include the "Upload-Limit" header field carrying all limits of
the corresponding upload if possible. This might not be possible if the corresponding upload if possible. This might not be possible if
intermediaries enforce limits. intermediaries enforce limits.
Servers, including intermediaries, can (and often do) apply Servers, including intermediaries, can (and often do) apply
restrictions on the size of individual request message content. restrictions on the size of individual request message content.
There is no standard mechanism to communicate such existing size There is no standard mechanism to communicate such existing size
restriction. A server that implements one can respond with a "413 restriction. A server that implements one can respond with a "413
(Content Too Large)" status code; see Section 15.5.14 of [HTTP]. (Content Too Large)" status code; see Section 15.5.14 of [HTTP].
Appending to an upload resource, as a series of appends, can be used Appending to an upload resource, as a series of appends, can be used
to upload data up to the "max-size" limit without encountering per- to upload data up to the "max-size" limit (Section 5.1.1) without
message limits. Servers might apply restrictions that are smaller encountering per-message limits. Servers might apply restrictions
than the append limits, which would also result in a failed request. that are smaller than the append limits, which would also result in a
failed request.
When a client receives a response with a "413 (Content Too Large)" When a client receives a response with a "413 (Content Too Large)"
status code during upload creation (Section 4.2) or append status code during upload creation (Section 6) or append (Section 8),
(Section 4.4), it SHOULD retry the request with a smaller size it SHOULD retry the request with a smaller size residing between
residing between "min-append-size" and "max-append-size". If these "min-append-size" (Section 5.1.4) and "max-append-size"
limits are unknown at the time of receiving such a response, the (Section 5.1.3). If these limits are unknown at the time of
client can attempt to discover them through an "OPTIONS" request. receiving such a response, the client can attempt to discover them
Retrying with the same request content size will likely yield the through an "OPTIONS" request (Section 5.2). Retrying with the same
same error response. Cases where the request content size matches request content size will likely yield the same error response.
the "min-append-size" limit yet fails with a "413 (Content Too Cases where the request content size matches the "min-append-size"
Large)" response might indicate a deployment mismatch that cannot be limit yet fails with a "413 (Content Too Large)" response might
recovered from. indicate a deployment mismatch that cannot be recovered from.
4.2. Upload Creation 6. Upload Creation
4.2.1. Client Behavior 6.1. Client Behavior
A client can start a resumable upload from any request that can carry A client can start a resumable upload from any request that can carry
content by including the "Upload-Complete" header field content by including the "Upload-Complete" header field
(Section 4.1.2). As a consequence, all request methods that allow (Section 4.2.1). Any method that allows content can be used, such as
content are possible, such as "POST", "PUT", and "PATCH". The "POST", "PUT", and "PATCH". The request can benefit from incremental
request can benefit from incremental delivery; see Section 11. delivery; see Section 18.
The "Upload-Complete" header field is set to true if the request The "Upload-Complete" header field is set to true if the request
content includes the entire representation data that the client content includes the entire representation data that the client
intends to upload. This is also a requirement for transparently intends to upload. This is also a requirement for transparently
upgrading to resumable uploads from conventional uploads upgrading to resumable uploads from conventional uploads
(Section 10.1.1). (Section 17.1.1).
If the client knows the representation's length, it SHOULD indicate If the client knows the representation's length, it SHOULD indicate
the length in the request to help the server allocate necessary the length in the request to help the server allocate necessary
resources for the upload and provide early feedback if the resources for the upload and provide early feedback if the
representation violates a limit (Section 4.1.4), as described in representation violates a limit (Section 5), as described in
Section 4.1.3. Section 4.3.
Clients are not required to discover limits (Section 4.1.4) before Clients are not required to discover limits (Section 5) before
starting the upload and might therefore be initially unaware of starting the upload and might therefore be initially unaware of
limits enforced by the server. However, the client SHOULD respect limits enforced by the server. However, the client SHOULD respect
any limits (Section 4.1.4) announced during the upload process in the any limits announced during the upload process in the "Upload-Limit"
"Upload-Limit" header field in interim or final responses. In header field in interim or final responses. In particular, if the
particular, if the allowed maximum size is less than the amount of allowed maximum size is less than the amount of representation data
representation data the client intends to upload, the client SHOULD the client intends to upload, the client SHOULD stop the current
stop the current request immediately (Section 12) and cancel the request immediately (Section 19) and cancel the upload (Section 9).
upload (Section 4.5). If the client knows that the representation If the client knows that the representation data is smaller than
data is smaller than "min-size", it cannot expect resumability to be "min-size" (Section 5.1.2), it cannot expect resumability to be
offered. The client might still attempt to transfer the offered. The client might still attempt to transfer the
representation in a single request, either in a request with the representation in a single request, either in a request with the
"Upload-Complete" header field set to true (see Section 10.1.1) or "Upload-Complete" header field set to true (see Section 17.1.1) or
via a conventional upload. via a conventional upload.
The request content can be empty. If the "Upload-Complete" header The request content can be empty. If the "Upload-Complete" header
field is then set to true, the client intends to upload an empty field is then set to true, the client intends to upload an empty
representation. An "Upload-Complete" header field set to false is representation. An "Upload-Complete" header field set to false is
also valid. This can be used to retrieve the upload resource's URI also valid. This can be used to retrieve the upload resource's URI
before transferring any representation data. Since interim responses before transferring any representation data. Since interim responses
are optional, this technique provides another mechanism to learn the are optional, this technique provides another mechanism to learn the
URI, at the cost of an additional round-trip before data upload can URI, at the cost of an additional round trip before data upload can
commence. commence.
Representation metadata included in the initial request (see Representation metadata included in the initial request (see
Section 8.2 of [HTTP]) can affect how servers act on the uploaded Section 8 of [HTTP]) can affect how servers act on the uploaded
representation data. The "Content-Type" header field (Section 8.3 of representation data. The "Content-Type" header field indicates the
[HTTP]) indicates the media type of the representation. The media type of the representation. The "Content-Encoding" header
"Content-Encoding" header field (Section 8.4 of [HTTP]) names the field names the content codings applied to the representation.
content codings applied to the representation. The "Content-
Disposition" header field ([CONTENT-DISPOSITION]) can be used to
transmit a filename. For this purpose, the "inline" disposition type
is RECOMMENDED.
If the client received a final response with the "Upload-Complete: If the client receives a final response that marks the upload as
?1" header field, the upload is complete and the corresponding complete, the response comes from the target resource of the initial
response comes from the resource processing the representation request (Section 4.2.1). Note that this does not necessarily
according to the initial request (Section 4.1.2). Note that this indicate success. "4xx (Client Error)" or "5xx (Server Error)" status
does not necessarily indicate success. "4xx (Client Error)" or "5xx codes indicate in this case an error occurred while processing the
(Server Error)" status codes indicate in this case an error occurred representation, and therefore, resuming the upload would not resolve
while processing the representation, and therefore, resuming the this error.
upload would not resolve this error.
If the client receives a 2xx successful final response with the If the client sent the "Upload-Complete" header field set to false
"Upload-Complete" header field set to false or missing, and the and receives a "2xx (Successful)" final response that does not mark
client's "Upload-Complete" request header field was set to false, the the upload as complete, the "Location" header field points the client
"Location" response header field points the client to the created to the created upload resource. The client can continue appending
upload resource. The client can continue appending representation representation data to it (Section 8).
data to it (Section 4.4).
If the client receives a 4xx client error or 5xx server error final If the client receives a "4xx (Client Error)" or "5xx (Server Error)"
response with the "Upload-Complete" header field set to false or final response that does not mark the upload as complete, or if it
missing, or if it did not receive a final response, it can apply the did not receive a final response, it can apply the heuristics
heuristics described in Section 4.7 to retry or resume the upload. described in Section 11 to retry or resume the upload.
4.2.2. Server Behavior 6.2. Server Behavior
Upon receiving a request with the "Upload-Complete" header field, the Upon receiving a request with the "Upload-Complete" header field, the
server can choose to offer resumption support for this request by server can choose to offer resumption support for this request by
creating an upload resource. If so, the server SHOULD announce the creating an upload resource. If so, the server SHOULD announce the
upload resource by sending an interim response with the "104 (Upload upload resource by sending an interim response with the "104 (Upload
Resumption Supported)" status code unless the server is not capable Resumption Supported)" status code unless the server is not capable
of sending interim responses. The interim response allows the client of sending interim responses. The interim response allows the client
to resume the upload even if the message exchange gets later to resume the upload even if the message exchange gets later
interrupted. When sent, it MUST include "Location" header field interrupted. When sent, it MUST include "Location" header field
pointing to the upload resource and MUST include the "Upload-Limit" pointing to the upload resource and MUST include the "Upload-Limit"
header field with the corresponding limits (Section 4.1.4) if header field with the corresponding limits (Section 5) if any.
existing.
The resource targeted by this initial request is responsible for The target resource of the initial request is responsible for
processing the representation data transferred in the resumable processing the representation data transferred in the resumable
upload according to the method and header fields in the initial upload according to the method and header fields in the initial
request. The upload resource, on the other hand, enables resuming request. The upload resource, on the other hand, enables resuming
the transfer. the transfer.
If the "Upload-Complete" request header field is set to true, the If the "Upload-Complete" request header field is set to true, the
client intends to transfer the entire representation data in one client intends to transfer the entire representation data in one
request. If the request content was fully processed, no resumable request. If the request content was fully processed, no resumable
upload is needed and the server proceeds to process the request and upload is needed and the server proceeds to process the request and
generate a response. The server MUST NOT emit a 2xx successful generate a response. Any "2xx (Successful)" response that the server
response with the "Upload-Complete" header field set to false or generates for such a request MUST mark the upload as complete.
missing in response to a request with the "Upload-Complete" request
header field set to true.
If the "Upload-Complete" request header field is set to false, the If the "Upload-Complete" request header field is set to false, the
client intends to transfer the representation over multiple requests. client intends to transfer the representation over multiple requests.
If the request content was fully processed, the server MUST include If the request content was fully processed, the server MUST include
the "Location" response header field pointing to the upload resource the "Location" header field pointing to the upload resource and MUST
and MUST include the "Upload-Limit" header field with the include the "Upload-Limit" header field with the corresponding limits
corresponding limits if existing. Servers are RECOMMENDED to use the if any. Servers are RECOMMENDED to use the "201 (Created)" status
"201 (Created)" status code. code.
The server MUST record the representation's length according to The server MUST record the representation's length according to
Section 4.1.3 if the "Upload-Length" or "Upload-Complete: ?1" header Section 4.3 if the "Upload-Length" or "Upload-Complete: ?1" header
fields are included in the request. fields are included in the request.
While the request content is being processed, the server MAY send While the request content is being processed, the server SHOULD send
multiple interim responses with a "104 (Upload Resumption Supported)" interim responses with a "104 (Upload Resumption Supported)" status
status code and the "Upload-Offset" header field set to the current code and the "Upload-Offset" header field set to the current offset
offset to inform the client about the upload progress. to inform the client about the upload progress.
Where a response requires a "Location" header field to be included, Every response to the same request that identifies the upload
all interim and final response messages for the same request MUST resource in the "Location" header field MUST use the same URI. A
contain an identical "Location" value. However, final responses final response with "Upload-Complete: ?1" is the result of processing
including the "Upload-Complete: ?1" header field are exempt from this the representation, so its "Location" header field can identify a
requirement because they are the result of processing the transferred different resource. Clients SHOULD check that the upload resource
representation and the "Location" value does not necessarily URI does not change, and SHOULD stop the current request immediately
represent the upload location. Where the "Location" value is (Section 19) and cancel the upload (Section 9) if it does.
expected to be identical across multiple messages, clients SHOULD
verify this. If verification fails, clients SHOULD abort the current
request and cancel the upload (Section 4.5).
The server SHOULD include the "Upload-Complete" (Section 4.1.2) The server SHOULD include the "Upload-Complete" header field
header field in the response to indicate whether it is the result of (Section 4.2.1) in the response to indicate whether it is the result
processing the uploaded representation. of processing the uploaded representation.
The server SHOULD NOT generate a response with the "301 (Moved The server SHOULD NOT generate a response with a "3xx (Redirection)"
Permanently)", "302 (Found)", or "303 (See Other)" status codes and status code and the "Upload-Complete: ?0" header field because the
the "Upload-Complete: ?0" header field because clients might follow upload resource's URI is expected to remain the same for the lifetime
the redirect without preserving the original method. See of the upload. See Section 20.7 for redirecting a response that
Section 13.1 for redirecting a response that completes the upload. completes the upload.
The server might not process the entire request content when the The server might not process the entire request content when the
upload is interrupted, for example because of dropped connection or upload is interrupted, for example, because of a dropped connection
canceled request. In this case, the server SHOULD append as much of or a canceled request. In this case, the server SHOULD append as
the request content as possible to the upload resource, allowing the much of the request content as possible to the upload resource,
client to resume the upload from where it was interrupted. In allowing the client to resume the upload from where it was
addition, the upload resource MUST NOT be considered complete then. interrupted. The upload resource MUST NOT be considered complete in
this case.
4.2.3. Examples 6.3. Examples
A) The following example shows an upload creation, where the entire A) The following example shows an upload creation, where all
123456789 bytes are transferred in the initial request. The server 123456789 bytes are transferred in the initial request. The server
sends multiple interim responses and one final response from sends multiple interim responses and one final response from
processing the uploaded representation. processing the uploaded representation.
POST /project/123/files HTTP/1.1 POST /project/123/files HTTP/1.1
Host: example.com Host: example.com
Content-Disposition: inline; filename="file name.jpg"; filename*=UTF-8''file%20name.jpg Content-Length: 123456789
Content-Length: 123456789 Upload-Length: 123456789
Upload-Length: 123456789 Upload-Complete: ?1
Upload-Complete: ?1
[content (123456789 bytes)]
[content (123456789 bytes)]
HTTP/1.1 104 Upload Resumption Supported HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/b530ce8ff Location: https://example.com/upload/b530ce8ff
Upload-Limit: max-size=1234567890 Upload-Limit: max-size=1234567890
HTTP/1.1 104 Upload Resumption Supported HTTP/1.1 104 Upload Resumption Supported
Upload-Offset: 23456789 Upload-Offset: 23456789
HTTP/1.1 200 OK HTTP/1.1 201 Created
Location: https://example.com/upload/b530ce8ff
Upload-Complete: ?1 Upload-Complete: ?1
Upload-Limit: max-size=1234567890 Location: https://example.com/project/123/files/b530ce8ff
Content-Type: application/json Content-Type: application/json
{"attachmentId": "b530ce8ff"} {"attachmentId": "b530ce8ff"}
B) The following example shows an upload creation, where only the B) The following example shows an upload creation, where only the
first 23456789 bytes of a 123456789 bytes upload are transferred. first 23456789 bytes of a 123456789-byte upload are transferred. The
The server acknowledges the processed representation data and that server acknowledges the processed representation data and that the
the upload is not complete yet. The client can continue appending upload is not complete yet. The client can continue appending data.
data.
POST /upload HTTP/1.1 POST /upload HTTP/1.1
Host: example.com Host: example.com
Upload-Complete: ?0 Upload-Complete: ?0
Content-Length: 23456789 Content-Length: 23456789
Upload-Length: 123456789 Upload-Length: 123456789
[partial content (23456789 bytes)] [partial content (23456789 bytes)]
HTTP/1.1 104 Upload Resumption Supported HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/3fd4994ad Location: https://example.com/upload/3fd4994ad
Upload-Limit: max-size=1234567890
HTTP/1.1 201 Created HTTP/1.1 201 Created
Location: https://example.com/upload/3fd4994ad Location: https://example.com/upload/3fd4994ad
Upload-Complete: ?0 Upload-Complete: ?0
Upload-Limit: max-size=1234567890 Upload-Limit: max-size=1234567890
C) The following example shows an upload creation, where the server C) The following example shows an upload creation, where the server
responds with a 5xx status code. Thanks to the interim response responds with a "5xx (Server Error)" status code. Thanks to the
containing the upload resource URI, the client can resume the upload. interim response containing the upload resource URI, the client can
resume the upload.
POST /upload HTTP/1.1 POST /upload HTTP/1.1
Host: example.com Host: example.com
Upload-Complete: ?1 Upload-Complete: ?1
Content-Length: 123456789 Content-Length: 123456789
Upload-Length: 123456789 Upload-Length: 123456789
[content (123456789 bytes)] [content (123456789 bytes)]
HTTP/1.1 104 Upload Resumption Supported HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/0587fa44b Location: https://example.com/upload/0587fa44b
HTTP/1.1 500 Internal Server Error HTTP/1.1 500 Internal Server Error
D) The following example shows an upload creation being rejected by D) The following example shows an upload creation being rejected by
the server because the request content cannot be decoded. The the server because the request content cannot be decoded. The
"Upload-Complete" header in the response is set to true since the "Upload-Complete" header field in the response is set to true
server is uninterested in receiving the full representation after the because, after the decoding failure, the server does not want the
decoding failure, and the upload is complete in its perspective. The rest of the representation and considers the upload complete. The
client cannot continue the upload. client cannot continue the upload.
POST /upload-gzip HTTP/1.1 POST /upload-gzip HTTP/1.1
Host: example.com Host: example.com
Upload-Complete: ?0 Upload-Complete: ?0
Content-Length: 23456789 Content-Length: 23456789
Upload-Length: 123456789 Upload-Length: 123456789
Content-Encoding: gzip Content-Encoding: gzip
[corrupted gzip content] [corrupted gzip content]
HTTP/1.1 104 Upload Resumption Supported HTTP/1.1 104 Upload Resumption Supported
Location: https://example.com/upload/6723cdf37 Location: https://example.com/upload/6723cdf37
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Upload-Complete: ?1 Upload-Complete: ?1
4.3. Offset Retrieval 7. Offset Retrieval
4.3.1. Client Behavior 7.1. Client Behavior
If the client wants to resume the upload after an interruption, it If the client wants to resume the upload after an interruption, it
has to know the amount of representation data processed by the upload has to know the amount of representation data processed by the upload
resource so far. It can fetch the offset by sending a "HEAD" or resource so far. It can fetch the offset by sending a "HEAD" or
"GET" request to the upload resource. Using "HEAD" is RECOMMENDED, "GET" request to the upload resource. Using "HEAD" is RECOMMENDED,
since response content is not required for resumption. Upon a since response content is not required for resumption. In a
successful response, the client can continue the upload by appending successful response, the "Upload-Offset" header field indicates the
representation data (Section 4.4) starting at the offset indicated by offset from which the client can continue the upload by appending
the "Upload-Offset" response header field. representation data (Section 8).
The offset can be less than or equal to the number of bytes of The offset can be less than or equal to the number of bytes of
representation data that the client has already sent. The client is representation data that the client has already sent. The client is
expected to handle backtracking of a reasonable length. On the other expected to handle backtracking of a reasonable length. On the other
hand, the offset can be greater than the amount of sent hand, the offset can be greater than the amount of sent
representation data, for example, if the server obtained additional representation data, for example, if the server already has data from
representation data on behalf of the client. If the client is not an earlier attempt to upload the same representation. If the client
able to provide the representation data at the given offset, the is not able to provide the representation data at the given offset,
upload MUST be considered a failure. The client then MUST NOT the upload MUST be considered a failure. The client then MUST NOT
continue the upload and SHOULD cancel the upload (Section 4.5). continue the upload and SHOULD cancel the upload (Section 9).
The client MUST NOT perform offset retrieval while the creation The client MUST NOT retrieve the offset while it is still creating
(Section 4.2) of or appending (Section 4.4) to the same upload (Section 6) or appending to (Section 8) the same upload resource,
resource is in progress as this can cause the previous request to be because the server might terminate the in-progress request
terminated by the server as described in Section 4.6. (Section 10).
If the client receives a 2xx successful response with a valid Upload- If the client receives a "2xx (Successful)" response with a valid
Offset header field, the client can continue appending representation "Upload-Offset" header field, the client can continue appending
data to it (Section 4.4). representation data to it (Section 8).
If the client receives a 2xx successful response without a valid If the client receives a "2xx (Successful)" response without a valid
Upload-Offset header field, a 4xx client error, or 5xx server error "Upload-Offset" header field, a "4xx (Client Error)" or "5xx (Server
response, or if it did not receive a response, the client MAY retry Error)" response, or if it did not receive a response, the client MAY
retrieving the offset. retry retrieving the offset. Otherwise, the upload is considered a
failure.
4.3.2. Server Behavior 7.2. Server Behavior
A successful response to a "HEAD" or "GET" request against an upload A successful response to a "HEAD" or "GET" request to an upload
resource resource
o MUST include the offset in the "Upload-Offset" header field o MUST include the offset in the "Upload-Offset" header field
(Section 4.1.1), (Section 4.1.1),
o MUST indicate the limits in the "Upload-Limit" header field o MUST indicate the limits in the "Upload-Limit" header field
(Section 4.1.4), and (Section 5) if any, and
o SHOULD include the "Cache-Control" header field with the value o SHOULD include the "Cache-Control" header field with the value
"no-store" to prevent HTTP caching ([CACHING]). "no-store" to prevent HTTP caching ([HTTP-CACHING]).
The server SHOULD NOT generate a response with the "301 (Moved The server SHOULD NOT generate a response with a "3xx (Redirection)"
Permanently)", "302 (Found)", or "303 (See Other)" status codes status code because the upload resource's URI is expected to remain
because clients might follow the redirect without preserving the the same for the lifetime of the upload.
"HEAD" method.
A client does not require response content for an offset retrieval A client does not require response content for an offset retrieval
request in order to successfully resume an upload. Therefore, request in order to successfully resume an upload. Therefore,
serving response content for a "GET" request is unexpected. Its serving response content for a "GET" request is unexpected. Its
meaning is not defined by this protocol. meaning is not defined by this protocol.
4.3.3. Examples 7.3. Examples
The following example shows an offset retrieval request. The server The following example shows an offset retrieval request. The server
indicates the current offset and that the upload is not complete yet. indicates the current offset and that the upload is not complete yet.
The client can continue to append representation data. The client can continue to append representation data.
HEAD /upload/c35e2cd29 HTTP/1.1 HEAD /upload/c35e2cd29 HTTP/1.1
Host: example.com Host: example.com
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Upload-Complete: ?0 Upload-Complete: ?0
Upload-Offset: 25000000 Upload-Offset: 25000000
Upload-Length: 100000000 Upload-Length: 100000000
Upload-Limit: max-age=3600 Upload-Limit: max-age=3600
Cache-Control: no-store Cache-Control: no-store
4.4. Upload Append 8. Upload Append
4.4.1. Client Behavior 8.1. Client Behavior
A client can continue the upload and append representation data by A client can continue the upload and append representation data by
sending a "PATCH" request with the "application/partial-upload" media sending a "PATCH" request with the "application/partial-upload" media
type (Section 6) to the upload resource. The request content is the type (Section 13) to the upload resource. The request content is the
representation data to append. The request can benefit from representation data to append. The request can benefit from
incremental delivery; see Section 11. incremental delivery; see Section 18.
The client MUST indicate the offset of the request content inside the The client MUST indicate the offset of the request content inside the
representation data by including the "Upload-Offset" header field. representation data by including the "Upload-Offset" header field.
To ensure that the upload resource will accept the request, the To ensure that the upload resource accepts the request, the client
offset SHOULD be taken from an immediate previous response for SHOULD take the offset from the most recent offset retrieval
retrieving the offset (Section 4.3), creating the upload (Section 7), upload creation (Section 6), or upload append response.
(Section 4.2), or appending representation data (Section 4.4).
The request content is the representation data to append, so the
patch document has no content coding of its own. A content coding
would make the request content differ from the representation data
that the offset (Section 4.1) and length (Section 4.3) count.
Therefore, the request MUST NOT include a "Content-Encoding" header
field (see Section 8.4 of [HTTP]). Content codings of the
representation, if any, are announced only in the upload creation
request (Section 6).
The request MUST include the "Upload-Complete" header field. Its The request MUST include the "Upload-Complete" header field. Its
value is true in two cases: value is true in two cases:
o the request has content that is the end of the representation o the request has content that is the end of the representation
data. Once the content is fully processed by the server, the data. Once the content is fully processed by the server, the
upload is complete. upload is complete.
o the request has no content. Once the request is processed by the o the request has no content. Once the request is processed by the
server, the upload is complete. This usage requires the full server, the upload is complete. This usage requires the full
representation data to have been processed during prior requests. representation data to have been processed during prior requests.
If the client received a final response with the "Upload-Complete: If the client receives a final response that marks the upload as
?1" header field, the upload is complete and the corresponding complete, the response comes from the target resource of the initial
response comes from the resource processing the representation request (Section 4.2.1). Note that this does not necessarily
according to the initial request (Section 4.1.2). Note that this indicate success. "4xx (Client Error)" or "5xx (Server Error)" status
does not necessarily indicate success. "4xx (Client Error)" or "5xx codes indicate in this case an error occurred while processing the
(Server Error)" status codes indicate in this case an error occurred representation, and therefore, resuming the upload would not resolve
while processing the representation, and therefore, resuming the this error.
upload would not resolve this error.
If the client received a 4xx client error or 5xx server error final If the client receives a "4xx (Client Error)" or "5xx (Server Error)"
response with the "Upload-Complete" header field set to false or final response that does not mark the upload as complete, or if it
missing, or if it did not receive a final response, it can apply the did not receive a final response, it can apply the heuristics
heuristics described in Section 4.7 to retry or resume the upload. described in Section 11 to retry or resume the upload. Otherwise,
Otherwise, the upload is considered a failure. the upload is considered a failure.
4.4.2. Server Behavior 8.2. Server Behavior
A server applies a "PATCH" request with the "application/partial- A server applies a "PATCH" request with the "application/partial-
upload" media type (Section 6) to an upload resource by appending the upload" media type (Section 13) to an upload resource by appending
patch document in the request content. the patch document in the request content.
The server might not process the entire patch document when the The server might not process the entire patch document when the
upload is interrupted, for example because of a dropped connection or upload is interrupted, for example, because of a dropped connection
canceled request. In this case, the server SHOULD append as much of or a canceled request. In this case, the server SHOULD append as
the patch document as possible to the upload resource, starting at much of the patch document as possible to the upload resource,
its beginning and without discontinuities. Appending a continuous starting at its beginning and without discontinuities. Appending a
section starting at the patch document's beginning constitutes a continuous section starting at the patch document's beginning
successful PATCH as defined in Section 2 of [PATCH]. Saving the constitutes a successful PATCH as defined in Section 2 of [PATCH].
processed data allows the client to resume the upload from where it Saving the processed data allows the client to resume the upload from
was interrupted. In addition, the upload resource MUST NOT be where it was interrupted. The upload resource MUST NOT be considered
considered complete then. complete in this case.
If the "Upload-Offset" request header field value does not match the If the "Upload-Offset" request header field value does not match the
current offset (Section 4.1.1), the server MUST reject the request current offset (Section 4.1), the server MUST reject the request with
with a "409 (Conflict)" status code and the "Upload-Complete" header a "409 (Conflict)" status code and the "Upload-Complete" header field
field set to false. The response MUST include the correct offset in set to false. The response MUST include the correct offset in the
the "Upload-Offset" header field. The response can use the problem "Upload-Offset" header field. The response can use the problem type
type [PROBLEM] of "https://iana.org/assignments/http-problem- [PROBLEM] of "https://iana.org/assignments/http-problem-
types#mismatching-upload-offset" (Section 7.1). types#mismatching-upload-offset" (Section 14.1).
If an upload append request is missing a valid "Upload-Offset" header
field, a valid "Upload-Complete" header field, or both, the server
SHOULD respond with a "400 (Bad Request)" status code.
The patch document cannot have a content coding of its own. A
content coding would make the request content differ from the
representation data that the offset (Section 4.1) and length
(Section 4.3) count. Therefore, if the request includes a "Content-
Encoding" header field, the server SHOULD respond with a "415
(Unsupported Media Type)" status code and the "Upload-Complete"
header field set to false.
If the "Upload-Complete" request header field is set to true, the If the "Upload-Complete" request header field is set to true, the
client intends to transfer the remaining representation data in one client intends to transfer the remaining representation data in one
request. If the request content was fully processed, the upload is request. If the request content was fully processed, the upload is
marked as complete and the server SHOULD generate the response that marked as complete and the server SHOULD generate the response that
matches what the resource, that was targeted by the initial upload matches what the target resource of the initial upload creation
creation (Section 4.2), would have generated if it had processed the request (Section 6) would have generated if it had processed the
entire representation in the initial request. However, the response entire representation in the initial request. However, the response
MUST include the "Upload-Complete" header field with a true value, MUST include the "Upload-Complete" header field set to true, allowing
allowing clients to identify whether a response, in particular error clients to identify whether a response, in particular error
responses, is related to the resumable upload itself or the responses, is related to the resumable upload itself or the
processing of the uploaded representation. The server MUST NOT emit processing of the uploaded representation. Any "2xx (Successful)"
a 2xx successful response with the "Upload-Complete" header field set response that the server generates for such a request MUST mark the
to false or missing in response to a request with the "Upload- upload as complete.
Complete" request header field set to true.
If the "Upload-Complete" request header field is set to false, the If the "Upload-Complete" request header field is set to false, the
client intends to transfer the remaining representation data over client intends to transfer the remaining representation data over
multiple requests. If the request content was fully processed, the multiple requests. If the request content was fully processed, the
server acknowledges the appended data by sending a "2xx (Successful)" server acknowledges the appended data by sending a "2xx (Successful)"
response with the "Upload-Complete" header field set to false. response with the "Upload-Complete" header field set to false.
Even if the upload is complete (Section 4.1.2) in the server's Even if the upload is complete (Section 4.2) from the server's
perspective and the final response from the targeted resource has perspective and the final response from the target resource of the
already been sent, the client might still perform an upload append initial request has already been sent, the client might still perform
(Section 4.4) after an offset retrieval (Section 4.3) due to the an upload append after an offset retrieval (Section 7) due to the
response being lost during transmission. The server can choose to response being lost during transmission. The server can choose to
replay the final response to the client if the request to append to replay the final response to the client if the request to append to
the completed upload is valid. the completed upload is valid.
The server MUST record the representation's length according to The server MUST record the representation's length according to
Section 4.1.3 if the "Upload-Length" or "Upload-Complete" header Section 4.3 if the "Upload-Length" or "Upload-Complete: ?1" header
fields are included in the request. If the representation's length fields are included in the request. If the representation's length
is known, the server MUST prevent the offset from exceeding the is known, the server MUST NOT let the offset exceed it: if appending
representation's length by rejecting the request once the offset a request's content would take the offset past the length, the server
exceeds the length, marking the upload resource invalid and rejecting MUST reject the request, deactivate the upload resource, and reject
any further interaction with it. It is not sufficient to rely on the any further interaction with it. It is not sufficient to rely on the
"Content-Length" header field for enforcement because this header "Content-Length" header field for enforcement because this header
field might not be present. field might not be present.
While the request content is being processed, the server SHOULD send While the request content is being processed, the server SHOULD send
interim responses with a "104 (Upload Resumption Supported)" status interim responses with a "104 (Upload Resumption Supported)" status
code and the "Upload-Offset" header field set to the current offset code and the "Upload-Offset" header field set to the current offset
to inform the client about the upload progress. These interim to inform the client about the upload progress. These interim
responses MUST NOT include the "Location" header field. responses MUST NOT include the "Location" header field.
The server SHOULD include the "Upload-Complete" (Section 4.1.2) The server SHOULD include the "Upload-Complete" header field
header field in the response to indicate whether it is the result of (Section 4.2.1) in the response to indicate whether it is the result
processing the uploaded representation. of processing the uploaded representation.
The server SHOULD NOT generate a response with the "301 (Moved The server SHOULD NOT generate a response with a "3xx (Redirection)"
Permanently)", "302 (Found)", or "303 (See Other)" status codes and status code and the "Upload-Complete: ?0" header field because the
the "Upload-Complete: ?0" header field because clients might follow upload resource's URI is expected to remain the same for the lifetime
the redirect without preserving the "PATCH" method. See Section 13.1 of the upload. See Section 20.7 for redirecting a response that
for redirecting a response that completes the upload. completes the upload.
4.4.3. Examples 8.3. Examples
A) The following example shows an upload append request. The client A) The following example shows an upload append request. The client
transfers the next 3456789 bytes at an offset of 20000000 and does transfers the next 3456789 bytes at an offset of 20000000 and does
not indicate that the upload is then completed. The server generates not indicate that the upload is then completed. The server generates
one interim response, when the offset reached 21728394 bytes, and one interim response, when the offset reached 21728394 bytes, and
finally acknowledges the new offset: finally acknowledges the new offset:
PATCH /upload/37a504d87 HTTP/1.1 PATCH /upload/37a504d87 HTTP/1.1
Host: example.com Host: example.com
Upload-Complete: ?0 Upload-Complete: ?0
skipping to change at page 26, line 19 skipping to change at page 28, line 4
Content-Length: 3456789 Content-Length: 3456789
Content-Type: application/partial-upload Content-Type: application/partial-upload
[content (3456789 bytes)] [content (3456789 bytes)]
HTTP/1.1 104 Upload Resumption Supported HTTP/1.1 104 Upload Resumption Supported
Upload-Offset: 21728394 Upload-Offset: 21728394
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
Upload-Complete: ?0 Upload-Complete: ?0
B) The following example shows an upload append, where the client
B) The next example shows an upload append, where the client
transfers the remaining 4567890 bytes and completes the upload with a transfers the remaining 4567890 bytes and completes the upload with a
length of 1234567890 bytes. The server processes the uploaded length of 1234567890 bytes. The server processes the uploaded
representation and generates the corresponding response, in this representation and generates the corresponding response, in this
example containing extracted meta data: example containing extracted metadata:
PATCH /upload/d38d6ffe8 HTTP/1.1 PATCH /upload/d38d6ffe8 HTTP/1.1
Host: example.com Host: example.com
Upload-Complete: ?1 Upload-Complete: ?1
Upload-Offset: 1230000000 Upload-Offset: 1230000000
Content-Length: 4567890 Content-Length: 4567890
Content-Type: application/partial-upload Content-Type: application/partial-upload
[content (4567890 bytes)] [content (4567890 bytes)]
HTTP/1.1 200 OK HTTP/1.1 200 OK
Upload-Complete: ?1 Upload-Complete: ?1
Content-Type: application/json Content-Type: application/json
{ {
"metadata": { "metadata": {
[...] [...]
} }
} }
4.5. Upload Cancellation 9. Upload Cancellation
4.5.1. Client Behavior 9.1. Client Behavior
If the client wants to terminate the transfer without the ability to If the client wants to cancel the upload, it can send a "DELETE"
resume, it can send a "DELETE" request to the upload resource. Doing request to the upload resource. Doing so is an indication that the
so is an indication that the client is no longer interested in client is no longer interested in continuing the upload, and that the
continuing the upload, and that the server can release any resources server can release any resources associated with it.
associated with it.
4.5.2. Server Behavior 9.2. Server Behavior
Upon receiving a "DELETE" request, the server SHOULD deactivate the Upon receiving a "DELETE" request, the server SHOULD deactivate the
upload resource. upload resource.
The server SHOULD terminate any in-flight requests to the upload The server SHOULD terminate any in-flight requests to the upload
resource before sending the response by abruptly terminating their resource before sending the response by abruptly terminating their
HTTP connection(s) or stream(s) as described in Section 4.6. HTTP connection(s) or stream(s), as described in Section 10.
The server SHOULD NOT generate a response with the "301 (Moved The server SHOULD NOT generate a response with a "3xx (Redirection)"
Permanently)", "302 (Found)", or "303 (See Other)" status codes status code because the upload resource's URI is expected to remain
because clients might follow the redirect without preserving the the same for the lifetime of the upload.
"DELETE" method.
4.5.3. Example 9.3. Example
The following example shows an upload cancellation: The following example shows an upload cancellation:
DELETE /upload/5688a431c HTTP/1.1 DELETE /upload/5688a431c HTTP/1.1
Host: example.com Host: example.com
HTTP/1.1 204 No Content HTTP/1.1 204 No Content
4.6. Concurrency 10. Concurrency
Resumable uploads, as defined in this document, do not permit This document does not support parallel requests that transfer
uploading representation data in parallel requests for the same representation data to the same upload resource. The client MUST NOT
upload. The client MUST NOT perform multiple representation data send an upload append request (Section 8) while an upload creation
transfers for the same upload resource in parallel, or perform request (Section 6) or another upload append request for the same
representation data transfers while the creation of the same upload upload resource is still in progress.
resource is still in progress.
Even if the client is well-behaved and doesn't send concurrent Even if the client is well-behaved and does not send concurrent
requests, network interruptions can occur in such a way that the requests, network interruptions can occur in such a way that the
client considers a request as failed while the server is unaware of client considers a request as failed while the server is unaware of
the problem and considers the request still ongoing. The client the problem and considers the request still ongoing. The client
might then try to resume the upload with the best intentions, might then try to resume the upload with the best intentions,
resulting in concurrent requests from the server's perspective. resulting in concurrent requests from the server's perspective.
Therefore, the server MUST take measures to prevent race conditions, Therefore, the server MUST take measures to prevent race conditions,
data loss and corruption from concurrent requests to append data loss, and corruption from concurrent append (Section 8) or
representation data (Section 4.4) and/or cancellation (Section 4.5) cancellation (Section 9) requests to the same upload resource. In
to the same upload resource. In addition, the server MUST NOT send addition, the server MUST NOT send outdated information in responses.
outdated information in responses. This means that the offset This means that if a client appends at an offset from a final
communicated through final responses as defined in Section 4.1.1 MUST response (Section 4.1.1), the server MUST NOT reject that request for
be accepted in a subsequent request to append representation data if having the wrong offset, unless another append or a cancellation
no other request to append representation data or cancel was received arrived in between.
in the meantime. In other words, clients have to be able to use
received offsets.
The RECOMMENDED approach is as follows: If a server receives a new The RECOMMENDED approach is as follows: If a server receives a new
request to retrieve the offset (Section 4.3), append representation request to retrieve the offset (Section 7), append representation
data (Section 4.4), or cancel the upload (Section 4.5) while a data (Section 8), or cancel the upload (Section 9) while a previous
previous request for creating the upload (Section 4.2) or appending request for creating the upload (Section 6) or appending
representation data (Section 4.4) to the same upload resource is representation data to the same upload resource is still ongoing, the
still ongoing, the server SHOULD prevent race conditions, data loss, server SHOULD prevent race conditions, data loss, and corruption by
and corruption by terminating the previous request before processing terminating the previous request before processing the new request.
the new request. Due to network delay and reordering, the server Due to network delay and reordering, the server might still be
might still be receiving representation data from an ongoing transfer receiving representation data from an ongoing transfer for the same
for the same upload resource, which in the client's perspective has upload resource, which from the client's perspective has failed.
failed. Since the client is not allowed to perform multiple Since the client is not allowed to perform multiple transfers for the
transfers for the same upload resource in parallel, the server can same upload resource in parallel, the server can assume that the
assume that the previous attempt has already failed. Therefore, the previous attempt has already failed. Therefore, the server MAY
server MAY abruptly terminate the previous HTTP connection or stream. abruptly terminate the previous HTTP connection or stream.
Since implementing this approach is not always technically possible Since implementing this approach is not always technically possible
or feasible, other measures can be considered as well. A simpler or feasible, other measures can be considered as well. A simpler
approach is that the server only processes a new request to retrieve approach is that the server only processes a new request to retrieve
the offset (Section 4.3), append representation data (Section 4.4), the offset (Section 7), append representation data (Section 8), or
or cancellation (Section 4.5) once all previous requests have been cancel the upload (Section 9) once all previous requests have been
processed. This effectively implements exclusive access to the processed. This effectively implements exclusive access to the
upload resource through an access lock. However, since network upload resource through an access lock. However, since network
interruptions can occur in ways that cause the request to hang from interruptions can occur in ways that cause the request to hang from
the server's perspective, it might take the server significant time the server's perspective, it might take the server significant time
to realize the interruption and time out the request. During this to realize the interruption and time out the request. During this
period, the client will be unable to access the resource and resume period, the client will be unable to access the resource and resume
the upload, causing friction for the end users. Therefore, the the upload, causing friction for the end users. Therefore, the
recommended approach is to terminate previous requests to enable recommended approach is to terminate previous requests to enable
quick resumption of uploads. quick resumption of uploads.
4.7. Retry 11. Retry
If the client received a 4xx client error or 5xx server error If the client receives a "4xx (Client Error)" or "5xx (Server Error)"
response with the "Upload-Complete" header field set to false or response that does not mark the upload as complete (Section 4.2.1)
missing when creating the upload resource (Section 4.2) or appending when creating the upload resource (Section 6) or appending to it
to it (Section 4.4), it can apply the heuristics described below to (Section 8), it can apply the heuristics described below to retry or
retry or resume the upload. resume the upload.
o "409 (Conflict)" with the "Upload-Complete" header field set to o "409 (Conflict)" with the "Upload-Complete" header field set to
false can be resumed with the correct offset (Section 4.1.1). If false: the upload can be resumed with the correct offset
no "Upload-Offset" header field is provided, the client SHOULD (Section 4.1). If no "Upload-Offset" header field is provided,
retrieve the offset (Section 4.3) before resuming. the client SHOULD retrieve the offset (Section 7) before resuming.
o "413 (Content Too Large)" can be resumed after applying o "413 (Content Too Large)": the upload can be resumed after
appropriate limits (Section 4.1.4). applying appropriate limits (Section 5).
o "429 (Too Many Requests)" can be retried after appropriate delays. o "429 (Too Many Requests)": the request can be retried after an
appropriate delay.
o "5xx (Server Error)" status codes can be retried. o "5xx (Server Error)": the request can be retried.
If no final response was received at all due to connectivity issues, If no final response was received at all due to connectivity issues,
the client MAY automatically attempt upload resumption by retrieving the client MAY automatically attempt upload resumption by retrieving
the current offset (Section 4.3). the current offset (Section 7).
The client SHOULD limit the number of retries it performs before The client SHOULD limit the number of retries it performs before
considering the upload a failure. considering the upload a failure, and SHOULD then cancel the upload
(Section 9) if it can still reach the upload resource.
5. Status Code 104 (Upload Resumption Supported) 12. Status Code 104 (Upload Resumption Supported)
The "104 (Upload Resumption Supported)" status code can be used for The "104 (Upload Resumption Supported)" status code can be used for
two purposes: two purposes:
o When responding to requests to create uploads, an interim response o When responding to requests to create uploads, a 104 interim
with the "104 (Upload Resumption Supported)" status code can be response can be sent to indicate the resource's support for
sent to indicate the resource's support for resumable uploads, as resumable uploads, as well as the URI and limits of the
well as the URI and limits of the corresponding upload resource in corresponding upload resource in the "Location" and "Upload-Limit"
the "Location" and "Upload-Limit" header fields, respectively (see header fields, respectively (see Section 6). This notifies the
Section 4.2). This notifies the client early about the ability to client early about the ability to resume the upload in case of
resume the upload in case of network interruptions. network interruptions.
o While processing the content of a request to append representation o While processing the content of a request to append representation
data or create an upload, the server can regularly send interim data or create an upload, the server can regularly send 104
responses with the "104 (Upload Resumption Supported)" status code interim responses to indicate the current upload progress in the
to indicate the current upload progress in the "Upload-Offset" "Upload-Offset" header field (see Section 6 and Section 8). This
header field (see Section 4.2 and Section 4.4). This allows the allows the client to show more accurate progress information about
client to show more accurate progress information about the amount the amount of data processed by the server. In addition, clients
of data processed by the server. In addition, clients can use can use this information to release representation data that was
this information to release representation data that was buffered, buffered, knowing that it does not have to be retransmitted.
knowing that it doesn't have to be retransmitted.
When creating or appending resumable uploads, the client can generate When creating or appending resumable uploads, the client can generate
a 100-continue expectation because it wants an indication that the a "100-continue" expectation because it wants an indication that the
resource is willing to accept the upload. The client MAY treat an resource is willing to accept the upload. The client MAY treat a 104
interim response with the "104 (Upload Resumption Supported)" status interim response as fulfilling the "100-continue" expectation and
code as fulfilling the 100-continue expectation and start sending the start sending the request content. However, the server MUST NOT omit
request content. However, the server MUST NOT omit the "100 the "100 (Continue)" response because it has sent a 104 interim
(Continue)" response because it has sent an interim response with the response.
"104 (Upload Resumption Supported)" status code.
6. Media Type application/partial-upload 13. Media Type application/partial-upload
The "application/partial-upload" media type describes a contiguous The "application/partial-upload" media type describes a contiguous
block from the representation data that should be uploaded to a block from the representation data to be uploaded to a resource.
resource. There is no minimum block size and the block might be There is no minimum block size and the block might be empty. The
empty. The block can be a subset of the representation data, where block can be a subset of the representation data, where the start
the start and/or end of the block don't line up with the start and/or and/or end of the block do not line up with the start and/or end of
end of the representation data respectively. the representation data respectively.
7. Problem Types 14. Problem Types
7.1. Mismatching Offset 14.1. Mismatching Offset
This section defines the "https://iana.org/assignments/http-problem- This section defines the "https://iana.org/assignments/http-problem-
types#mismatching-upload-offset" problem type [PROBLEM]. A server types#mismatching-upload-offset" problem type [PROBLEM]. A server
can use this problem type when responding to an upload append request can use this problem type when responding to an upload append request
(Section 4.4) to indicate that the "Upload-Offset" header field in (Section 8) to indicate that the "Upload-Offset" header field in the
the request does not match the upload resource's offset. request does not match the upload resource's offset.
Two problem type extension members are defined: the "expected-offset" Two problem type extension members are defined: the "expected-offset"
and "provided-offset" members. A response using this problem type and "provided-offset" members. Both are non-negative integers. A
SHOULD populate both members, with the value of "expected-offset" response using this problem type SHOULD populate both members, with
taken from the upload resource and the value of "provided-offset" the value of "expected-offset" taken from the upload resource and the
taken from the upload append request. value of "provided-offset" taken from the upload append request.
The following example shows an example response, where the resource's The following example shows a response, where the resource's offset
offset was 12500000, but the client attempted to append at offset was 12500000, but the client attempted to append at offset 25000000:
25000000:
# NOTE: '\' line wrapping per RFC 8792 # NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 409 Conflict HTTP/1.1 409 Conflict
Content-Type: application/problem+json Content-Type: application/problem+json
Upload-Offset: 12500000 Upload-Offset: 12500000
Upload-Complete: ?0 Upload-Complete: ?0
{ {
"type":"https://iana.org/assignments/http-problem-types#\ "type":"https://iana.org/assignments/http-problem-types#\
mismatching-upload-offset", mismatching-upload-offset",
"title": "offset from request does not match offset of resource", "title": "offset from request does not match offset of resource",
"expected-offset": 12500000, "expected-offset": 12500000,
"provided-offset": 25000000 "provided-offset": 25000000
} }
7.2. Inconsistent Length 14.2. Inconsistent Length
This section defines the "https://iana.org/assignments/http-problem- This section defines the "https://iana.org/assignments/http-problem-
types#inconsistent-upload-length" problem type [PROBLEM]. A server types#inconsistent-upload-length" problem type [PROBLEM]. A server
can use this problem type when responding to an upload creation can use this problem type when responding to an upload creation
(Section 4.2) or upload append request (Section 4.4) to indicate that (Section 6) or upload append request (Section 8) to indicate that the
the request includes inconsistent length values, as described in request includes inconsistent length values, as described in
Section 4.1.3. Section 4.3.
The following example shows an example response: The following example shows a response:
# NOTE: '\' line wrapping per RFC 8792 # NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/problem+json Content-Type: application/problem+json
Upload-Complete: ?0 Upload-Complete: ?0
{ {
"type":"https://iana.org/assignments/http-problem-types#\ "type":"https://iana.org/assignments/http-problem-types#\
inconsistent-upload-length", inconsistent-upload-length",
"title": "inconsistent length values for upload" "title": "inconsistent length values for upload"
} }
8. Content Codings 15. Content Codings
Since the codings listed in "Content-Encoding" are a characteristic Since the codings listed in the "Content-Encoding" header field are a
of the representation (see Section 8.4 of [HTTP]), both the client characteristic of the representation (see Section 8.4 of [HTTP]),
and the server always compute the values for "Upload-Offset" and both the client and the server always compute the values for the
optionally "Upload-Length" on the content coded data (that is, the "Upload-Offset" and optionally "Upload-Length" header fields on the
representation data). Moreover, the content codings are retained content coded data (that is, the representation data). Moreover, the
throughout the entire upload, meaning that the server is not required content codings are retained throughout the entire upload, meaning
to decode the representation data to support resumable uploads. See that the server is not required to decode the representation data to
Appendix A of [DIGEST-FIELDS] for more information. support resumable uploads. The content codings, if any, are
announced in the upload creation request (Section 6) and not repeated
when appending representation data (Section 8).
9. Transfer Codings 16. Transfer Codings
Unlike "Content-Encoding" (see Section 8.4.1 of [HTTP]), "Transfer- Unlike content codings (see Section 8.4.1 of [HTTP]), transfer
Encoding" (see Section 6.1 of [RFC9112]) is a property of the codings (see Section 6.1 of [RFC9112]) are a property of the message,
message, not of the representation. Moreover, transfer codings can not of the representation. Moreover, transfer codings can be applied
be applied in transit (e.g., by proxies). This means that a client in transit (e.g., by proxies). This means that a client does not
does not have to consider the transfer codings to compute the upload have to consider the transfer codings to compute the upload offset,
offset, while a server is responsible for transfer decoding the while a server is responsible for transfer decoding the message
message before computing the upload offset. The same applies to the before computing the upload offset. The same applies to the "Upload-
value of "Upload-Length". Please note that the "Content-Length" Length" header field value. See Section 6.2 of [RFC9112] for how the
header field cannot be used in conjunction with the "Transfer- "Content-Length" and "Transfer-Encoding" header fields interact.
Encoding" header field.
10. Upload Strategies 17. Upload Strategies
The definition of the upload creation request (Section 4.2) provides The definition of the upload creation request (Section 6) provides
the client with flexibility to choose whether the representation data the client with flexibility to choose whether the representation data
is fully or partially transferred in the first request, or if no is fully or partially transferred in the first request, or if no
representation data is included at all. Which behavior is best representation data is included at all. Which behavior is best
largely depends on the client's capabilities, its desire to avoid largely depends on the client's capabilities, its desire to avoid
data retransmission, and its knowledge about the resource's support data retransmission, and its knowledge about the resource's support
for resumable uploads. for resumable uploads.
The following subsections describe two typical upload strategies that The following subsections describe two typical upload strategies that
are suited for common environments. Note that these modes are never are suited for common environments. Note that these strategies are
explicitly communicated to the server and clients are not required to never explicitly communicated to the server, and clients are not
stick to one strategy, but can mix and adapt them to their needs. required to use only one strategy but can mix and adapt them to their
needs.
10.1. Optimistic Upload Creation 17.1. Optimistic Upload Creation
An "optimistic upload creation" can be used independent of the An "optimistic upload creation" can be used regardless of the
client's knowledge about the resource's support for resumable client's knowledge about the resource's support for resumable
uploads. However, the client must be capable of handling and uploads. However, the client needs to be able to process interim
processing interim responses. An upload creation request then responses. An upload creation request then includes the full
includes the full representation data because the client anticipates representation data because the client anticipates that it will be
that it will be transferred without interruptions or resumed if an transferred without interruptions or resumed if an interruption
interruption occurs. occurs.
The benefit of this method is that if the upload creation request The benefit of this strategy is that if the upload creation request
succeeded, the representation data was transferred in a single succeeds, the representation data is transferred in a single request
request without additional round trips. without additional round trips.
A possible drawback is that the client might be unable to resume an A possible drawback is that the client might be unable to resume an
upload. If an upload is interrupted before the client receives a upload. If an upload is interrupted before the client receives a
"104 (Upload Resumption Supported)" interim response with the upload "104 (Upload Resumption Supported)" interim response with the upload
resource's URI, the client cannot resume that upload due to the resource's URI, the client cannot resume that upload due to the
missing URI. The interim response might not be received if the missing URI. The interim response might not be received if the
interruption happens too early in the message exchange, the resource interruption happens too early in the message exchange, the target
targeted in the initial request does not support resumable uploads, resource of the initial request does not support resumable uploads,
the server is not capable of sending the "104 (Upload Resumption the server is not capable of sending the 104 interim response, or an
Supported)" interim response, or an intermediary dropped the interim intermediary dropped the interim response. Without a 104 interim
response. Without a 104 response, the client needs to either treat response, the client needs to either treat the upload as failed or
the upload as failed or retry the entire upload creation request if retry the entire upload creation request if this is allowed by the
this is allowed by the application. application.
A client might wait for a limited duration to receive a 104 (Upload A client might wait for a limited duration to receive a 104 interim
Resumption Supported) interim response before starting to transmit response before starting to transmit the request content. This way,
the request content. This way, the client can learn about the the client can learn about the resource's support for resumable
resource's support for resumable uploads and/or the upload resource's uploads and/or the upload resource's URI. This is conceptually
URI. This is conceptually similar to how a client might wait for a similar to how a client might wait for a "100 (Continue)" interim
100 (Continue) interim response (see Section 10.1.1 of [HTTP]) before response (see Section 10.1.1 of [HTTP]) before committing to work.
committing to work.
10.1.1. Upgrading To Resumable Uploads 17.1.1. Upgrading to Resumable Uploads
Optimistic upload creation allows clients and servers to Optimistic upload creation allows clients and servers to
automatically upgrade non-resumable uploads to resumable ones. In a automatically upgrade non-resumable uploads to resumable ones. In a
non-resumable upload, the representation is transferred in a single non-resumable upload, the representation is transferred in a single
request, usually "POST" or "PUT", without any ability to resume from request, usually "POST" or "PUT", without any ability to resume from
interruptions. The client can invite the server to upgrade such a interruptions. The client can invite the server to upgrade such a
request to a resumable upload by adding the "Upload-Complete: ?1" request to a resumable upload by adding the "Upload-Complete: ?1"
header field to the original request. The "Upload-Length" header header field to the original request. The "Upload-Length" header
field SHOULD be added if the representation's length is known field SHOULD be added if the representation's length is known
upfront. The request is not changed otherwise. upfront. The request is not changed otherwise.
If the resource targeted in the initial request supports resumable If the target resource of the initial request supports resumable
uploads, the server can create an upload resource and send its URI in uploads, the server can create an upload resource and send its URI in
a "104 (Upload Resumption Supported)" interim response for the client a 104 interim response for the client to resume the upload after
to resume the upload after interruptions. A resource that does not interruptions. A resource that does not support resumable uploads or
support resumable uploads or does not want to upgrade to a resumable does not want to upgrade to a resumable upload for this request
upload for this request ignores the "Upload-Complete: ?1" header. ignores the "Upload-Complete: ?1" header field. The transfer then
The transfer then falls back to a non-resumable upload without falls back to a non-resumable upload without additional cost.
additional cost.
This upgrade can also be performed transparently by a library or This upgrade can also be performed transparently by a library or
program that acts as an HTTP client by sending requests on behalf of program that acts as an HTTP client by sending requests on behalf of
a user. When the user instructs the client to send a non-resumable a user. When the user instructs the client to send a non-resumable
request, the client can perform the upgrade transparently and handle request, the client can perform the upgrade transparently and handle
potential interruptions and resumptions under the hood without potential interruptions and resumptions under the hood without
involving the user. The last response received by the client is involving the user. The last response received by the client is
considered the response for the entire upload and should be provided considered the response for the entire upload and needs to be
to the user. provided to the user.
10.2. Careful Upload Creation 17.2. Careful Upload Creation
For a "careful upload creation" the client knows that the resource For a "careful upload creation" the client knows that the target
targeted in the initial request supports resumable uploads and sends resource of the initial request supports resumable uploads and sends
an empty upload creation request without including any representation an empty upload creation request without including any representation
data. Upon successful response reception, the client can use the data. Upon successful response reception, the client can use the
included upload resource URI to transmit the representation data included upload resource URI to transmit the representation data
(Section 4.4) and resume the upload at any stage if an interruption (Section 8) and resume the upload at any stage if an interruption
occurs. The client should inspect the response for the "Upload- occurs. The response can include the "Upload-Limit" header field,
Limit" header field, which would indicate limits applying to the which indicates limits for the rest of the upload (Section 5).
remaining upload procedure.
The retransmission of representation data or the ultimate upload The retransmission of representation data or the ultimate upload
failure that can happen with an "optimistic upload creation" is failure that can happen with an "optimistic upload creation" is
therefore avoided at the expense of an additional request that does therefore avoided at the expense of an additional request that does
not carry representation data. not carry representation data.
This approach is best suited if the client cannot receive interim This approach is best suited if the client cannot receive interim
responses, e.g., due to a limitation in the provided HTTP interface, responses, e.g., due to a limitation in the provided HTTP interface,
or if large representations are transferred where the cost of the or if large representations are transferred where the cost of the
additional request is minuscule compared to the effort of additional request is minuscule compared to the effort of
transferring the representation itself. transferring the representation itself.
11. Incremental Transfer, Processing and Forwarding 18. Incremental Transfer, Processing, and Forwarding
The resumable upload design is most effective when a server processes The resumable upload design is most effective when a server processes
request message portions as they arrive, which ensures the greatest request message portions as they arrive, which ensures the greatest
chance that data is processed before a possible transfer chance that data is processed before a possible transfer
interruption. interruption.
To support incremental processing, it is RECOMMENDED that clients To support incremental processing, it is RECOMMENDED that clients
send request content incrementally and minimize buffering. send request content incrementally and minimize buffering.
As described in [INCREMENTAL], intermediaries might interfere with As described in [INCREMENTAL], intermediaries might interfere with
the incremental delivery of data to a server. Clients can use the the incremental delivery of data to a server. Clients can use the
"Incremental" header field defined in Section 3 of [INCREMENTAL] to "Incremental" header field defined in Section 3 of [INCREMENTAL] to
signal their preference for incremental forwarding by intermediaries. signal their preference for incremental forwarding by intermediaries.
12. Request Cancellation 19. Request Cancellation
A client or server might want to interrupt an in-flight message A client or server might want to interrupt an in-flight message
transfer intentionally for various reasons (see Section 1). The transfer intentionally for various reasons (see Section 1). The
mechanism to do so depends on the HTTP version in use: mechanism to do so depends on the HTTP version in use:
HTTP/1.1: close the underlying transport connection (Section 9.5 of HTTP/1.1: close the underlying transport connection (Section 9.5 of
[RFC9112]) [RFC9112])
HTTP/2: send a "RST_STREAM" frame (Section 6.4 of [RFC9113]) HTTP/2: reset the stream (Section 6.4 of [RFC9113])
HTTP/3: send a "RESET_STREAM" (Section 19.4 of [QUIC]) or HTTP/3: abruptly terminate the request stream (Section 4.1.1 of
"STOP_SENDING" frame (Section 19.5 of [QUIC]) [RFC9114])
Version-specific mechanisms place requirements on clients or servers Version-specific mechanisms place requirements on clients or servers
for actioning the cancellation. However, for all versions of HTTP, for carrying out the cancellation. However, for all versions of
resumable uploads allow the server to process received representation HTTP, resumable uploads allow the server to process received
data and expose the upload offset via the upload resource, enabling representation data and expose the upload offset via the upload
continuation of the upload after interruption. resource, enabling continuation of the upload after interruption.
13. Security Considerations 20. Security Considerations
20.1. Upload Resource URIs
The upload resource URI is the identifier used for modifying the The upload resource URI is the identifier used for modifying the
upload. Without further protection of this URI, an attacker may upload. Without further protection of this URI, an attacker can
obtain information about an upload, append data to it, or cancel it. perform any operation on the upload resource: obtain information
To prevent this, the server SHOULD ensure that only authorized about it, append data to it, or cancel it. Each of these requests
clients can access the upload resource. To reduce the risk of can also cause a server to terminate an in-flight request from a
unauthorized access, it is RECOMMENDED to generate upload resource legitimate client (Section 10).
URIs in such a way that makes it hard to be guessed by unauthorized
clients. In addition, servers may embed information about the
storage or processing location of the uploaded representation in the
upload resource URI to make routing requests more efficient. If so,
they MUST ensure that no internal information is leaked in the URI
that is not intended to be exposed.
Uploaded representation data and its metadata are untrusted input. To mitigate these risks, the server SHOULD ensure that only
Server operators have to be careful of where uploaded data is written authorized clients can access the upload resource. It is also
and subsequently accessed, especially if the operations cause the RECOMMENDED that upload resource URIs be hard to guess.
representation to be processed or executed by the server. In
addition, metadata MUST be validated and/or sanitized if the server Servers might embed information in the upload resource URI, such as a
takes its values into consideration for processing or storing the storage or processing location, to make request routing more
representation. efficient. Because the URI is visible to the client and to anyone
else who obtains it, servers MUST NOT include information in it that
is not intended to be exposed. Routing information could, for
instance, be encoded so that only the server can interpret it.
If knowing the upload resource URI is enough to access the upload,
the URI is in effect a credential. Like other credentials, it needs
to be protected in transit (see Section 17.16.1 of [HTTP]). URIs are
also often logged or displayed by servers, proxies, and user agents,
so the URI can be disclosed to third parties (see Section 17.9 of
[HTTP]).
20.2. Untrusted Input
Upload creation and upload append requests carry untrusted input; see
Section 17.3 of [HTTP] and Section 17.4 of [HTTP].
20.3. Content Scanning
Some servers or intermediaries provide scanning of content uploaded Some servers or intermediaries provide scanning of content uploaded
by clients. Any scanning mechanism that relies on receiving a by clients. Any scanning mechanism that relies on receiving a
complete representation in a single request message can be defeated complete representation in a single request message can be defeated
by resumable uploads because content can be split across multiple by resumable uploads because content can be split across multiple
messages. Servers or intermediaries wishing to perform content messages. Servers or intermediaries wishing to perform content
scanning SHOULD consider how resumable uploads can circumvent scanning SHOULD consider how resumable uploads can circumvent
scanning and take appropriate measures. Possible strategies include scanning and take appropriate measures. Possible strategies include
waiting for the upload to complete before scanning the entire waiting for the upload to complete before scanning the entire
representation, or disabling resumable uploads. representation, or disabling resumable uploads.
20.4. Time-of-Check to Time-of-Use
There can be a significant delay between the creation of an upload There can be a significant delay between the creation of an upload
resource and its completion. Policy decisions or authorization resource and its completion. Policy decisions or authorization
checks performed on the initial request might become outdated or checks performed on the initial request might become outdated or
invalid by the time the upload completes. To mitigate invalid by the time the upload completes. To mitigate
vulnerabilities arising from time-of-check to time-of-use (TOCTOU) vulnerabilities arising from time-of-check to time-of-use (TOCTOU)
conditions, the server SHOULD validate that the user is still allowed conditions, the server SHOULD validate that the user is still allowed
to perform the requested action before finalizing the upload. This to perform the requested action before finalizing the upload. This
includes, for example, validating access privileges and quota includes, for example, validating access privileges and quota
policies associated with the upload resource. policies associated with the upload resource.
20.5. Resource Exhaustion
Resumable uploads are vulnerable to Slowloris-style attacks Resumable uploads are vulnerable to Slowloris-style attacks
[SLOWLORIS]. A malicious client may create upload resources and keep [SLOWLORIS]. A malicious client can create upload resources and keep
them alive by regularly sending "PATCH" requests with no or small them alive by regularly sending "PATCH" requests with no or small
content to the upload resources. This could be abused to exhaust content to the upload resources. This could be abused to exhaust
server resources by creating and holding open uploads indefinitely server resources by creating and holding open uploads indefinitely
with minimal work. Servers SHOULD provide mitigations for Slowloris with minimal work. Servers SHOULD provide mitigations for Slowloris
attacks, such as increasing the maximum number of clients the server attacks, such as increasing the maximum number of clients the server
will allow, limiting the number of uploads a single client is allowed will allow, limiting the number of uploads a single client is allowed
to make, imposing restrictions on the minimum transfer speed an to make, imposing restrictions on the minimum transfer speed an
upload is allowed to have, and restricting the length of time an upload is allowed to have, and restricting the length of time an
upload resource can exist. upload resource can exist.
20.6. Message Size Limits
Uploads performed as a series of appends can be used to upload data Uploads performed as a series of appends can be used to upload data
up to the "max-size" limit, which could be a larger size than a up to the "max-size" limit (Section 5.1.1), which could be a larger
server or intermediary might normally permit in conventional single size than a server or intermediary might normally permit in
upload request message content. Servers or intermediaries need to conventional single upload request message content. Servers or
consider that relying solely on message content limits to constrain intermediaries need to consider that relying solely on message
resources allocated to uploads might not be an effective strategy content limits to constrain resources allocated to uploads might not
when using resumable uploads. be an effective strategy when using resumable uploads.
13.1. Different Origins 20.7. Different Origins
The resource targeted by the initial request (Section 4.2) and the The target resource of the initial request (Section 6) and the upload
upload resource might have different origins ([ORIGIN]). For resource might have different origins ([ORIGIN]). For example, the
example, the initial request might be sent to an application server, initial request might be sent to an application server, while the
while the upload resource is hosted by a dedicated storage service. upload resource is hosted by a dedicated storage service.
Clients have to consider this change of origin when following the Clients have to consider this change of origin when following the
"Location" header field to the upload resource. Credentials and "Location" header field to the upload resource. Credentials and
other per-origin state associated with the initially targeted other per-origin state associated with the target resource of the
resource are not necessarily applicable to the upload resource, and initial request are not necessarily applicable to the upload
remain scoped to their respective origins. Clients also have to resource, and remain scoped to their respective origins. Clients
consider that disclosing an upload resource URI to a different origin also have to consider that disclosing an upload resource URI to a
can leak the capability to read, append to, or cancel the upload. different origin can leak the capability to read, append to, or
cancel the upload.
Because the upload can be completed either by the initial request or Because the upload can be completed either by the initial request or
by an upload append request (Section 4.4), the final response might by an upload append request, the final response might come from a
come from a different origin depending on whether the upload was different origin depending on whether the upload was resumed. To
resumed. To avoid this, the server MAY respond to the request that avoid this, the server MAY respond to the request that completes the
completes the upload with a "303 (See Other)" status code, upload with a "303 (See Other)" status code, redirecting the user
redirecting the user agent to the origin of the initially targeted agent to the origin of the target resource of the initial request.
resource. Because a "303 (See Other)" response directs the user
agent to retrieve the result with "GET", the considerations regarding
method preservation in Section 4.2 and Section 4.4 do not apply in
this case.
14. IANA Considerations 21. IANA Considerations
14.1. HTTP Fields 21.1. HTTP Fields
IANA is asked to register the following entries in the "Hypertext IANA is asked to register the following entries in the "Hypertext
Transfer Protocol (HTTP) Field Name Registry": Transfer Protocol (HTTP) Field Name Registry":
+-----------------+-----------+-------------+-----------------------+ +-----------------+-----------+---------------+---------------------+
| Field Name | Status | Structured | Reference | | Field Name | Status | Structured | Reference |
| | | Type | | | | | Type | |
+-----------------+-----------+-------------+-----------------------+ +-----------------+-----------+---------------+---------------------+
| Upload-Offset | permanent | Item | Section 4.1.1 of this | | Upload-Offset | permanent | Item | Section 4.1.1 of |
| | | | document | | | | | RFC nnnn |
| | | | | | | | | |
| Upload-Complete | permanent | Item | Section 4.1.2 of this | | Upload-Complete | permanent | Item | Section 4.2.1 of |
| | | | document | | | | | RFC nnnn |
| | | | | | | | | |
| Upload-Length | permanent | Item | Section 4.1.3 of this | | Upload-Length | permanent | Item | Section 4.3.1 of |
| | | | document | | | | | RFC nnnn |
| | | | | | | | | |
| Upload-Limit | permanent | Dictionary | Section 4.1.4 of this | | Upload-Limit | permanent | Dictionary | Section 5.1 of RFC |
| | | | document | | | | | nnnn |
+-----------------+-----------+-------------+-----------------------+ +-----------------+-----------+---------------+---------------------+
14.2. HTTP Status Code 21.2. HTTP Status Code
IANA is asked to register the following entry in the "HTTP Status IANA is asked to register the following entry in the "Hypertext
Codes" registry: Transfer Protocol (HTTP) Status Code Registry":
Value: 104 (suggested value) Value: 104 (suggested value)
Description: Upload Resumption Supported Description: Upload Resumption Supported
Specification: Section 5 of this document Specification: Section 12 of RFC nnnn
14.3. Media Type 21.3. Media Type
IANA is asked to register the following entry in the "Media Types" IANA is asked to register the following entry in the "Media Types"
registry: registry:
Type name: application Type name: application
Subtype name: partial-upload Subtype name: partial-upload
Required parameters: N/A Required parameters: N/A
Optional parameters: N/A Optional parameters: N/A
Encoding considerations: binary Encoding considerations: binary
Security considerations: see Section 13 of this document Security considerations: see Section 20 of RFC nnnn
Interoperability considerations: N/A Interoperability considerations: N/A
Published specification: Section 6 of this document Published specification: Section 13 of RFC nnnn
Applications that use this media type: Applications that transfer Applications that use this media type: Applications that transfer
files over unreliable networks or want pause- and resumable files over unreliable networks or want pausable and resumable
uploads. uploads.
Fragment identifier considerations: N/A Fragment identifier considerations: N/A
Additional information: Additional information:
o Deprecated alias names for this type: N/A o Deprecated alias names for this type: N/A
o Magic number(s): N/A o Magic number(s): N/A
skipping to change at page 38, line 33 skipping to change at page 40, line 33
Authors' Addresses section of this document. Authors' Addresses section of this document.
Intended usage: COMMON Intended usage: COMMON
Restrictions on usage: N/A Restrictions on usage: N/A
Author: See the Authors' Addresses section of this document. Author: See the Authors' Addresses section of this document.
Change controller: IETF Change controller: IETF
14.4. HTTP Problem Types 21.4. HTTP Problem Types
IANA is asked to register the following entry in the "HTTP Problem IANA is asked to register the following entry in the "HTTP Problem
Types" registry: Types" registry:
Type URI: https://iana.org/assignments/http-problem- Type URI: https://iana.org/assignments/http-problem-
types#mismatching-upload-offset types#mismatching-upload-offset
Title: Mismatching Upload Offset Title: Mismatching Upload Offset
Recommended HTTP status code: 409 Recommended HTTP status code: 409
Reference: Section 7.1 of this document Reference: Section 14.1 of RFC nnnn
IANA is asked to register the following entry in the "HTTP Problem IANA is asked to register the following entry in the "HTTP Problem
Types" registry: Types" registry:
Type URI: https://iana.org/assignments/http-problem- Type URI: https://iana.org/assignments/http-problem-
types#inconsistent-upload-length types#inconsistent-upload-length
Title: Inconsistent Upload Length Values Title: Inconsistent Upload Length Values
Recommended HTTP status code: 400 Recommended HTTP status code: 400
Reference: Section 7.2 of this document Reference: Section 14.2 of RFC nnnn
15. References
15.1. Normative References
[CACHING] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Caching", STD 98, RFC 9111,
DOI 10.17487/RFC9111, June 2022,
<https://www.rfc-editor.org/info/rfc9111>.
[CONTENT-DISPOSITION] 22. References
Reschke, J., "Use of the Content-Disposition Header Field
in the Hypertext Transfer Protocol (HTTP)", RFC 6266,
DOI 10.17487/RFC6266, June 2011,
<https://www.rfc-editor.org/info/rfc6266>.
[DIGEST-FIELDS] 22.1. Normative References
Polli, R. and L. Pardue, "Digest Fields", RFC 9530,
DOI 10.17487/RFC9530, February 2024,
<https://www.rfc-editor.org/info/rfc9530>.
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110, Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022, DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>. <https://www.rfc-editor.org/info/rfc9110>.
[HTTP-CACHING]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Caching", STD 98, RFC 9111,
DOI 10.17487/RFC9111, June 2022,
<https://www.rfc-editor.org/info/rfc9111>.
[PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP", [PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, DOI 10.17487/RFC5789, March 2010, RFC 5789, DOI 10.17487/RFC5789, March 2010,
<https://www.rfc-editor.org/info/rfc5789>. <https://www.rfc-editor.org/info/rfc5789>.
[PROBLEM] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details [PROBLEM] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details
for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023, for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023,
<https://www.rfc-editor.org/info/rfc9457>. <https://www.rfc-editor.org/info/rfc9457>.
[QUIC] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based
Multiplexed and Secure Transport", RFC 9000,
DOI 10.17487/RFC9000, May 2021,
<https://www.rfc-editor.org/info/rfc9000>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC9112] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [RFC9112] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112,
June 2022, <https://www.rfc-editor.org/info/rfc9112>. June 2022, <https://www.rfc-editor.org/info/rfc9112>.
[RFC9113] Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113, [RFC9113] Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113,
DOI 10.17487/RFC9113, June 2022, DOI 10.17487/RFC9113, June 2022,
<https://www.rfc-editor.org/info/rfc9113>. <https://www.rfc-editor.org/info/rfc9113>.
[RFC9114] Bishop, M., Ed., "HTTP/3", RFC 9114, DOI 10.17487/RFC9114,
June 2022, <https://www.rfc-editor.org/info/rfc9114>.
[STRUCTURED-FIELDS] [STRUCTURED-FIELDS]
Nottingham, M. and P. Kamp, "Structured Field Values for Nottingham, M. and P. Kamp, "Structured Field Values for
HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024, HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024,
<https://www.rfc-editor.org/info/rfc9651>. <https://www.rfc-editor.org/info/rfc9651>.
15.2. Informative References [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
22.2. Informative References
[INCREMENTAL] [INCREMENTAL]
Oku, K., Pauly, T., and M. Thomson, "Incremental Oku, K., Pauly, T., and M. Thomson, "Incremental
Forwarding of HTTP Messages", RFC 10036, Forwarding of HTTP Messages", RFC 10036,
DOI 10.17487/RFC10036, August 2026, DOI 10.17487/RFC10036, August 2026,
<https://www.rfc-editor.org/info/rfc10036>. <https://www.rfc-editor.org/info/rfc10036>.
[ORIGIN] Barth, A., "The Web Origin Concept", RFC 6454, [ORIGIN] Barth, A., "The Web Origin Concept", RFC 6454,
DOI 10.17487/RFC6454, December 2011, DOI 10.17487/RFC6454, December 2011,
<https://www.rfc-editor.org/info/rfc6454>. <https://www.rfc-editor.org/info/rfc6454>.
skipping to change at page 40, line 45 skipping to change at page 42, line 38
"Handling Long Lines in Content of Internet-Drafts and "Handling Long Lines in Content of Internet-Drafts and
RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020,
<https://www.rfc-editor.org/info/rfc8792>. <https://www.rfc-editor.org/info/rfc8792>.
[SLOWLORIS] [SLOWLORIS]
"RSnake" Hansen, R., "Welcome to Slowloris - the low "RSnake" Hansen, R., "Welcome to Slowloris - the low
bandwidth, yet greedy and poisonous HTTP client!", June bandwidth, yet greedy and poisonous HTTP client!", June
2009, <https://web.archive.org/web/20150315054838/ 2009, <https://web.archive.org/web/20150315054838/
http://ha.ckers.org/slowloris/>. http://ha.ckers.org/slowloris/>.
15.3. URIs 22.3. URIs
[1] https://tus.io/ [1] https://tus.io/
Appendix A. Changes Appendix A. Changes
This section is to be removed before publishing as an RFC. This section is to be removed before publishing as an RFC.
A.1. Since draft-ietf-httpbis-resumable-upload-12 A.1. Since draft-ietf-httpbis-resumable-upload-15
No changes yet.
A.2. Since draft-ietf-httpbis-resumable-upload-14
o State that unknown Structured Fields parameters MUST be ignored.
o Discourage change of upload URLs.
o Append request cannot use different content codings.
o Define ranges for integer values in "Upload-Limit" and problem
type members.
A.3. Since draft-ietf-httpbis-resumable-upload-13
Editorial changes only.
A.4. Since draft-ietf-httpbis-resumable-upload-12
o Upload-Complete and Upload-Length are no longer required on offset o Upload-Complete and Upload-Length are no longer required on offset
retrieval responses. retrieval responses.
o Remove discouragement against sending requests after expiration. o Remove discouragement against sending requests after expiration.
o Clarify how upload offset is inferred from responses. o Clarify how upload offset is inferred from responses.
o Disallow successful responses indicating an incomplete upload when o Disallow successful responses indicating an incomplete upload when
the request indicated completion. the request indicated completion.
o Describe considerations for the initially targeted resource and o Describe considerations for the initially targeted resource and
the upload resource having different origins. the upload resource having different origins.
A.2. Since draft-ietf-httpbis-resumable-upload-11 A.5. Since draft-ietf-httpbis-resumable-upload-11
o Clear up different responsibilities of server and upload resource. o Clear up different responsibilities of server and upload resource.
o Relax recommendations on client handling greater offsets. o Relax recommendations on client handling greater offsets.
o Clarify client behavior for 413 responses. o Clarify client behavior for 413 responses.
o Remove Accept-Patch from OPTIONS responses. o Remove Accept-Patch from OPTIONS responses.
o Allow upload creation requests with no content regardless of the o Allow upload creation requests with no content regardless of the
skipping to change at page 42, line 15 skipping to change at page 44, line 26
o Clarify that clients might not know limits when starting upload. o Clarify that clients might not know limits when starting upload.
o Remove section covering integrity digests. o Remove section covering integrity digests.
o Increase the draft interop version. o Increase the draft interop version.
o Add version-specific details on cancelling in-flight transfers. o Add version-specific details on cancelling in-flight transfers.
o Clarify client retry strategies. o Clarify client retry strategies.
A.3. Since draft-ietf-httpbis-resumable-upload-10 A.6. Since draft-ietf-httpbis-resumable-upload-10
o Add recommended disposition type for file name indication. o Add recommended disposition type for file name indication.
A.4. Since draft-ietf-httpbis-resumable-upload-09 A.7. Since draft-ietf-httpbis-resumable-upload-09
o Requires Accept-Patch in OPTIONS. o Requires Accept-Patch in OPTIONS.
o Add security consideration regarding time-of-check to time-of-use. o Add security consideration regarding time-of-check to time-of-use.
o Lift requirement on Upload-Complete for all final responses. o Lift requirement on Upload-Complete for all final responses.
o Relax requirements on limit changes. o Relax requirements on limit changes.
o Describe the interaction between 100 and 104 responses. o Describe the interaction between 100 and 104 responses.
o Numerous editorial improvements. o Numerous editorial improvements.
A.5. Since draft-ietf-httpbis-resumable-upload-08 A.8. Since draft-ietf-httpbis-resumable-upload-08
o Clarify definitions of new header fields. o Clarify definitions of new header fields.
o Make handling of OPTIONS * optional. o Make handling of OPTIONS * optional.
o Require server to announce limits using Upload-Limit. o Require server to announce limits using Upload-Limit.
o Require clients to adhere to known limits. o Require clients to adhere to known limits.
o Rephrase requirements for concurrency handling, focusing on the o Rephrase requirements for concurrency handling, focusing on the
outcome. outcome.
o Remove requirement for 204 status code for DELETE responses. o Remove requirement for 204 status code for DELETE responses.
o Increase the draft interop version. o Increase the draft interop version.
o Add section about 104 status code. o Add section about 104 status code.
o Rephrase recommendation for sending information back to client. o Rephrase recommendation for sending information back to client.
A.6. Since draft-ietf-httpbis-resumable-upload-07 A.9. Since draft-ietf-httpbis-resumable-upload-07
o Clarify server handling when upload length is exceeded. o Clarify server handling when upload length is exceeded.
o Extend security considerations about upload resource URIs, o Extend security considerations about upload resource URIs,
representation metadata, and untrusted inputs. representation metadata, and untrusted inputs.
o Allow clients to retry for appropriate 4xx responses. o Allow clients to retry for appropriate 4xx responses.
A.7. Since draft-ietf-httpbis-resumable-upload-06 A.10. Since draft-ietf-httpbis-resumable-upload-06
o Minor editorial improvements to introduction and examples. o Minor editorial improvements to introduction and examples.
o Define structured types for new header fields. o Define structured types for new header fields.
A.8. Since draft-ietf-httpbis-resumable-upload-05 A.11. Since draft-ietf-httpbis-resumable-upload-05
o Increase the draft interop version. o Increase the draft interop version.
o Numerous editorial changes. o Numerous editorial changes.
o Rename "expires" limit to "max-age". o Rename "expires" limit to "max-age".
o Require "Upload-Complete", but not "Upload-Offset" or "Upload- o Require "Upload-Complete", but not "Upload-Offset" or "Upload-
Limit", for append responses. Limit", for append responses.
o Add problem type for inconsistent length values. o Add problem type for inconsistent length values.
o Reduce use of "file" in favor of "representation". o Reduce use of "file" in favor of "representation".
A.9. Since draft-ietf-httpbis-resumable-upload-04 A.12. Since draft-ietf-httpbis-resumable-upload-04
o Clarify implications of "Upload-Limit" header. o Clarify implications of "Upload-Limit" header.
o Allow client to fetch upload limits upfront via "OPTIONS". o Allow client to fetch upload limits upfront via "OPTIONS".
o Add guidance on upload creation strategy. o Add guidance on upload creation strategy.
o Add "Upload-Length" header to indicate length during creation. o Add "Upload-Length" header to indicate length during creation.
o Describe possible usage of "Want-Repr-Digest". o Describe possible usage of "Want-Repr-Digest".
A.10. Since draft-ietf-httpbis-resumable-upload-03 A.13. Since draft-ietf-httpbis-resumable-upload-03
o Add note about "Content-Location" for referring to subsequent o Add note about "Content-Location" for referring to subsequent
resources. resources.
o Require "application/partial-upload" for appending to uploads. o Require "application/partial-upload" for appending to uploads.
o Explain handling of content and transfer codings. o Explain handling of content and transfer codings.
o Add problem types for mismatching offsets and completed uploads. o Add problem types for mismatching offsets and completed uploads.
o Clarify that completed uploads must not be appended to. o Clarify that completed uploads must not be appended to.
o Describe interaction with Digest Fields from RFC9530. o Describe interaction with Digest Fields from RFC9530.
o Require that upload offset does not decrease over time. o Require that upload offset does not decrease over time.
o Add Upload-Limit header field. o Add Upload-Limit header field.
o Increase the draft interop version. o Increase the draft interop version.
A.11. Since draft-ietf-httpbis-resumable-upload-02 A.14. Since draft-ietf-httpbis-resumable-upload-02
o Add upload progress notifications via informational responses. o Add upload progress notifications via informational responses.
o Add security consideration regarding request filtering. o Add security consideration regarding request filtering.
o Explain the use of empty requests for creation uploads and o Explain the use of empty requests for creation uploads and
appending. appending.
o Extend security consideration to include resource exhaustion o Extend security consideration to include resource exhaustion
attacks. attacks.
o Allow 200 status codes for offset retrieval. o Allow 200 status codes for offset retrieval.
o Increase the draft interop version. o Increase the draft interop version.
A.12. Since draft-ietf-httpbis-resumable-upload-01 A.15. Since draft-ietf-httpbis-resumable-upload-01
o Replace Upload-Incomplete header with Upload-Complete. o Replace Upload-Incomplete header with Upload-Complete.
o Replace terminology about procedures with HTTP resources. o Replace terminology about procedures with HTTP resources.
o Increase the draft interop version. o Increase the draft interop version.
A.13. Since draft-ietf-httpbis-resumable-upload-00 A.16. Since draft-ietf-httpbis-resumable-upload-00
o Remove Upload-Token and instead use Server-generated upload URL o Remove Upload-Token and instead use Server-generated upload URL
for upload identification. for upload identification.
o Require the Upload-Incomplete header field in Upload Creation o Require the Upload-Incomplete header field in Upload Creation
Procedure. Procedure.
o Increase the draft interop version. o Increase the draft interop version.
A.14. Since draft-tus-httpbis-resumable-uploads-protocol-02 A.17. Since draft-tus-httpbis-resumable-uploads-protocol-02
None None
A.15. Since draft-tus-httpbis-resumable-uploads-protocol-01 A.18. Since draft-tus-httpbis-resumable-uploads-protocol-01
o Clarifying backtracking and preventing skipping ahead during the o Clarifying backtracking and preventing skipping ahead during the
Offset Receiving Procedure. Offset Receiving Procedure.
o Clients auto-retry 404 is no longer allowed. o Clients auto-retry 404 is no longer allowed.
A.16. Since draft-tus-httpbis-resumable-uploads-protocol-00 A.19. Since draft-tus-httpbis-resumable-uploads-protocol-00
o Split the Upload Transfer Procedure into the Upload Creation o Split the Upload Transfer Procedure into the Upload Creation
Procedure and the Upload Appending Procedure. Procedure and the Upload Appending Procedure.
Appendix B. Draft Version Identification Appendix B. Draft Version Identification
This section is to be removed before publishing as an RFC. This section is to be removed before publishing as an RFC.
To assist the development of implementations and interoperability To assist the development of implementations and interoperability
testing while this document is still a draft, an interop version is testing while this document is still a draft, an interop version is
skipping to change at page 47, line 4 skipping to change at page 49, line 16
Marius Kleidl (editor) Marius Kleidl (editor)
Transloadit Transloadit
Email: ietf@mariuskleidl.net Email: ietf@mariuskleidl.net
Guoye Zhang (editor) Guoye Zhang (editor)
Apple Inc. Apple Inc.
Email: guoye_zhang@apple.com Email: guoye_zhang@apple.com
Lucas Pardue (editor) Lucas Pardue (editor)
Cloudflare Apple
Email: lucas@lucaspardue.com Email: lucas@lucaspardue.com
 End of changes. 258 change blocks. 
846 lines changed or deleted 958 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/