Overall, it is very solid and I like it.
A few minor points:
If the upload completes successfully, the server MUST respond with a
201 Createdstatus.
[…]
For each successful chunk, the server MUST respond with a202 Acceptedheader, except for the final chunk, which MUST be a201 Created, and as with non-chunked uploads, the body of these responses has no content.
This seems to assume the processing of the final chunk will always be synchronous, which is a bit inconsistent with how the session is handled asynchronously. I can imagine that at this point, there could be some delay, e.g. because server verifies the checksum of the uploaded file in one step. However, I’m not sure if making this potentially asynchronous (i.e. returning 202 and expecting the client to recheck status later) is worth the added complexity.
If the offset provided in
Upload-Offsetis not0or correctly specifies the byte offset of the next chunk in an incomplete upload, then the server MUST respond with a409 Conflict. This means that a client MAY NOT upload chunks out of order.
I find this sentence really hard to parse. It sounds like it means “if the offset … correctly specifies the byte offset of the next chunk in an incomplete upload, then the server…” — but wasn’t it supposed to mean the opposite of that? Also, shouldn’t that be “MUST NOT”? “MAY NOT” is not in RFC 2119, and I honestly find it confusing.
Perhaps:
If the offset provided in
Upload-Offsetis not0and does not correctly specify the byte offset of the next chunk in an incomplete upload, then the server MUST respond with a409 Conflict. This means that a client MUST NOT upload chunks out of order.
Canceling an In-Progress Upload
[…]
Delete a Partial or Fully Uploaded File
Isn’t “deleting a partial file” and “canceling an upload” essentially the same thing? Also, the latter section only covers fully uploaded files, so perhaps it should either be renamed, or both sections merged into one.
Complete the in-progress upload by uploading a zero-length chunk providing the
Upload-Complete: ?1header. This effectively truncates and completes the in-progress upload, after which point the new upload can commence. In this case, clients SHOULD reuse the previous upload resource URL and do not need to begin the entire file upload sequence over again.
What is the use case for this? FWIU it implies that the file must have the same size and hashes, so I don’t really understand what would be the circumstances under which the client would suddenly need to start uploading the same file over again.
I think error responses are underspecified. In particular, HTTP error codes are listed only in handful of cases. I think it would be worthwhile to at least list some common errors that can be expected from issuing different requests.