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: Integer. The "min-size" key specifies a minimum size for a resumable <del> upload, counted in bytes.  The server will not create an upload </del> <ins> upload, counted in bytes.  The server MAY NOT create an upload </ins> resource if the client indicates that the uploaded data is smaller <del> than the minimum size.  The value is an Integer. </del> <ins> than the minimum size by including the "Content-Length" and "Upload-Complete: ?1" fields, but the server MAY still accept the uploaded data.  The value is an Integer. </ins> The "max-append-size" key specifies a maximum size counted in bytes for the request content in a single upload append request