Code change:
an upload.  For example, a subsequent resource could allow the client to fetch information extracted from the uploaded data. <del> 16. </del> <ins> 17. The definition of the upload creation request (upload-creation) provides the client with flexibility to choose whether the file is fully or partially transferred in the first request, or if no file data is included at all.  Which behavior is best largely depends on the client's capabilities, its intention to avoid data re- transmission, and its knowledge about the server's support for resumable uploads. The following subsections describe two typical upload strategies that are suited for common environments.  Note that these modes are never explicitly communicated to the server and clients are not required to stick to one strategy, but can mix and adapt them to their needs. 17.1. An "optimistic upload creation" can be used independent of the client's knowledge about the server's support for resumable uploads. However, the client must be capable of handling and processing interim responses.  An upload creation request then includes the full file because the client anticipates that the file will be transferred without interruptions or resumed if an interruption occurs. The benefit of this method is that if the upload creation request succeeds, the file was transferred in a single request without additional round trips. A possible drawback is that the client might be unable to resume an upload.  If an upload is interrupted before the client received a "104 (Upload Resumption Supported)" intermediate response with the upload URL, the client cannot resume that upload due to the missing upload URL.  The intermediate response might not be received if the interruption happens too early in the message exchange, the server does not support resumable uploads at all, the server does not support sending the "104 (Upload Resumption Supported)" intermediate response, or an intermediary dropped the intermediate response. Without a 104 response, the client needs to either treat the upload as failed or retry the entire upload creation request if this is allowed by the application. 17.1.1. Optimistic upload creation allows clients and servers to automatically upgrade non-resumable uploads to resumable ones.  In a non-resumable upload, the file is transferred in a single request, usually "POST" or "PUT", without any ability to resume from interruptions.  The client can offer the server to upgrade such a request to a resumable upload (see feature-detection) by adding the "Upload-Complete: ?1" header field to the original request.  The request is not changed otherwise. A server that supports resumable uploads at the target URI can create a resumable upload resource and send its upload URL in a "104 (Upload Resumption Supported)" intermediate response for the client to resume the upload after interruptions.  A server that does not support resumable uploads or does not want to upgrade to a resumable upload for this request ignores the "Upload-Complete: ?1" header.  The transfer then falls back to a non-resumable upload without additional cost. This upgrade can also be performed transparently by the client without the user taking an active role.  When a user asks the client to send a non-resumable request, the client can perform the upgrade and handle potential interruptions and resumptions under the hood without involving the user.  The last response received by the client is considered the response for the entire file upload and should be presented to the user. 17.2. For a "careful upload creation" the client knows that the server supports resumable uploads and sends an empty upload creation request without including any file data.  Upon successful response reception, the client can use the included upload URL to transmit the file data (upload-appending) and resume the upload at any stage if an interruption occurs.  The client should inspect the response for the "Upload-Limit" header field, which would indicate limits applying to the remaining upload procedure. The retransmission of file data or the ultimate upload failure that can happen with an "optimistic upload creation" is therefore avoided at the expense of an additional request that does not carry file data. This approach best suited if the client cannot receive intermediate responses, e.g. due to a limitation in the provided HTTP interface, or if large files are transferred where the cost of the additional request is miniscule compared to the effort of transferring the large file itself. 18. </ins> The upload resource URL is the identifier used for modifying the upload.  Without further protection of this URL, an attacker may

Related discussion:
text: The definition of upload creation requests allows the client to include the entire file, some file data or no data at all. While we provide this flexibility, we don't give guidance on when which approach is best suited. This PR adds this missing piece and explains how an optimistic client can attempt to upload the file in one request and how a careful client uses a separate request for creating the upload. In addition, it also mentions how to transparently upgrade to resumable uploads, which wasn't explained in detail before. Let me know if you have any feedback on this.
Are "Optimistic Upload Creation" and "Upgrading To Resumable Uploads" the exact same way? Maybe the 3rd way could be checking first before uploading?
The way they are described right now they are similar, yes. In theory, an optimistic upload creation can also be used where the client doesn't upload the entire file, but just a large part of it (think 500 MB of a 10 GB file). When upgrading a non-resumable request to a resumable upload, this act of division is not allowed. But I am not sure if we should go into that much detail here. If not, then we can merge these two sections. Upload limits are a good point! With the careful upload, the client also knows the limits before sending the first PATCH request. The optimistic client must be prepared to receive a 104 response with limits that it has to adapt to. We can mention that a careful client may also send an OPTIONS request before hand if it deems that necessary.
I think upload-limit can just be enforced on the server side. If it sends a 104 and a 5xx response, the client would automatically retry. We have deployed a client-side implementation that is not aware of the upload-limit header field.
Thanks for all of your comments! I updated the PR to put the section about upgrading to resumable uploads under the optimistic upload creation since they are similar. I also added a brief mention of Upload-Limit and shortened the text a bit. Let me know if you think the text needs more adjustments.
Just a minor nit. Otherwise I think this is a very good addition and agree with NAME that we should add some text with regards to the .