Resumable Uploads: application/partial-upload media type
#2743
Conversation
| @@ -324,7 +324,7 @@ The client SHOULD NOT automatically retry if a client error status code between | |||
|
|
|||
| Upload appending is used for resuming an existing upload. | |||
|
|
|||
| The request MUST use the `PATCH` method and be sent to the upload resource. The `Upload-Offset` field value ({{upload-offset}}) MUST be set to the resumption offset. | |||
| The request MUST use the `PATCH` method and `application/partial-upload` media type and be sent to the upload resource. The `Upload-Offset` field value ({{upload-offset}}) MUST be set to the resumption offset. | |||
There was a problem hiding this comment.
I feel that this sentence is a bit off, probably due to language barriers on my end.
Suggested edit:
The request MUST use the
PATCHmethod withapplication/partial-uploadas content type and be sent to the upload resource. TheUpload-Offsetfield value ({{upload-offset}}) MUST be set to the resumption offset.
| @@ -336,6 +336,8 @@ The client MUST NOT perform multiple upload transfers for the same upload resour | |||
|
|
|||
| If the offset indicated by the `Upload-Offset` field value does not match the offset provided by the immediate previous offset retrieval ({{offset-retrieving}}), or the end offset of the immediate previous incomplete successful transfer, the server MUST respond with a `409 (Conflict)` status code. | |||
|
|
|||
| The server applies the patch document of the `application/partial-upload` media type by appending the unmodified request content to the targeted upload resource. | |||
There was a problem hiding this comment.
To me "unmodified" reads as "take the entire thing and apply it without changes" which is probably not what is intended here? The server is not allowed to pick bytes that it appends, but I think we need to clarify that the entire request must not complete for the server to append data. I.e. if the connection breaks down after 100 bytes then as much as possible of those 100 bytes should be appended and what is appended must be appended without modification.
| # Media Type `application/partial-upload` | ||
|
|
||
| The `application/partial-upload` media type describes a contiguous block of data that should be uploaded to a resource. There is no minimum size on the block of data and it might be empty. The start and end of block of data might align with the start and end of the file that should be uploaded, but are not required to do so. | ||
|
|
There was a problem hiding this comment.
Minor nit:
The start and end of THE block of data might align with the start and end of the file that should be uploaded, but are not required to do so.
or
The start and end of THE data might align with the start and end of the file that should be uploaded, but are not required to do so.
Should we avoid using "file" as the thing to be uploaded and use something more generic like "resource that should be uploaded"?
As discussed in #2501 and #2610, the PATCH requests needs a suiting media type to describe the message content.
Since there does not seem to be an existing, suitable media type, we proposed the
application/partial-uploadmedia type on the media-types mailing list. This PR is a first, rough attempt at including such a media type in the draft.