Code change:
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 . Proposal for optimistic: The client needs to adapt to the header provided in the intermediate response and fail the request if the file is larger than the maximum allowed size. Proposal for Careful: The client can use the header provided in the to verify that the file is allowed to be uploaded before sending any data.Some editorial suggestions, but one big question: What is the material difference between the first and third strategy? Could these be the same strategy?

Related discussion:
text: Clients can send representation metadata (see HTTP) in the request that starts an upload.  Servers MAY interpret this metadata or MAY ignore it.  The "Content-Type" header field (HTTP) can be used to <del> indicate the media type of the file.  The content coding of the representation is specified using the "Content-Encoding" header field and is retained throughout the entire upload.  When resuming an interrupted upload, the same content coding is used for appending to the upload, producing a representation of the upload resource with one consistent content coding.  The "Content-Disposition" header field (RFC6266) can be used to transmit a filename; if included, the parameters SHOULD be either "filename", "filename*" or "boundary". </del> <ins> indicate the media type of the file.  The applied content codings are specified using the "Content-Encoding" header field and are retained throughout the entire upload.  When resuming an interrupted upload, the same content codings are used for appending to the upload, producing a representation of the upload resource.  The "Content- Disposition" header field (RFC6266) can be used to transmit a filename; if included, the parameters SHOULD be either "filename", "filename*" or "boundary". </ins> 4.1.