Resumable File Uploads¶
Large video files can be uploaded using a resumable file upload protocol. This method allows to continue file upload only for the remaining part of the file after a network interruption.
Resumable file upload performed using a two-step process:
- First, the API create or update call is done. The call will return an upload URL and an upload session ID.
- Second, the file is submitted to this upload URL in small chunks using HTTP POST method. If upload is interrupted, it can be resumed from the last position acknowledged by the upload server.
After executing an API call that has a resumable upload option, its response will include a link block with parameters that can be used to construct the upload URL. For example, here is the response of a /videos/create API call:
<?xml version="1.0" encoding="UTF-8"?> <response> <status>ok</status> <video key="tL17msiU"> <link> <protocol>http</protocol> <address>upload.bitsontherun.com</address> <path>/v1/videos/upload/resumable</path> <query> <key>vtQmcboj</key> </query> </link> <session_id>kwJei9j2vtQmcbojrlGJY3mbJFMHfzZwPXBwoSQr</session_id> </video> </response>
The upload URL should be concatenated from the parts of the link block using the following scheme:
upload_url = <link/protocol> + "://" + <link/address> + <link/path> + "?api_format=<one of: py, json, xml, php>" + "&key=" + <link/query/key> + "&redirect_address=" + <redirect_address> + "&redirect_query.<param_name1>=" + <param_value1> + "&redirect_query.<param_name2>=" + <param_value2> + "&key_in_path=" + <key_in_path>
That should produce the following upload URL using response example from above:
http://upload.bitsontherun.com/v1/videos/upload/resumable ?api_format=xml &key=vtQmcboj
In addition to the parameters in the link block, the following redirect query parameters can be added to the upload URL:
- redirect_address (optional) : string
Redirect address string using the following format:
- redirect_query.param (optional) : string
Redirect query parameter. param part of the redirect parameters (after the ‘.’ separator) specifies name of the parameter. Redirect query parameter can be specified multiple times, as far as parameter name is unique.
- key_in_path (optional) : string
Specifies if //video/@key should be added as a query parameter to the redirect URL, or at the end of the URL path.
Add value of the //video/@key at the end of the URL path:
Add value of the //video/@key as video_key query parameter:
Default is False.
When using these redirect parameters, the upload URL should look like this:
http://upload.bitsontherun.com/v1/videos/upload/resumable ?api_format=xml &key=vtQmcboj &redirect_address=http://example.com/path &redirect_query.parameter1=value1 &redirect_query.parameter2=value2 &key_in_path=True
After upload URL has been constructed, it can be used to upload file chunks.
Example request to upload the first file chunk¶
POST /v1/videos/upload/resumable ?api_format=xml &key=vtQmcboj &redirect_address=http://example.com/path &redirect_query.parameter1=value1 &redirect_query.parameter2=value2 &key_in_path=True HTTP/1.1 Host: upload.bitsontherun.com Content-Length: 1234567 Content-Disposition: attachment; filename="video.mpeg" Content-Type: application/octet-stream X-Content-Range: bytes 0-1234566/96768273 X-Session-ID: kwJei9j2vtQmcbojrlGJY3mbJFMHfzZwPXBwoSQr <bytes 0-1234566>
The following headers must be provided in addition to the default ones:
- Content-Disposition : string
- Content-Type : string
MIME type of a file being uploaded. MIME type must not be set to multipart/form-data. If MIME type of the file cannot be determined, application/octet-stream type may be used.
- X-Content-Range : string
Byte range of the chunk being uploaded and total size of the file in bytes:
The first byte of a file has number 0, the last byte has number n-1, where n is the size of the file in bytes.
The body of the request must contain a chunk of the file corresponding to the range that was specified in X-Content-Range header.
Example response after uploading a file chunk¶
HTTP/1.1 201 Created Date: Wed, 08 Aug 2012 09:24:34 GMT Content-Length: 18 Range: 0-1234566/96768273 0-1234566/96768273
Upload server acknowledges successful reception of the file chunk with 201 Created HTTP status in the response. Client then may proceed with uploading of the next file chunk.
- Range : string
Received byte range - a combination of byte ranges from all uploaded file chunks.
Received byte range. Same as in the Range header.
Example request to upload the last file chunk¶
POST /v1/videos/upload/resumable ?api_format=xml &key=vtQmcboj &redirect_address=http://example.com/path &redirect_query.parameter1=value1 &redirect_query.parameter2=value2 &key_in_path=True HTTP/1.1 Host: upload.bitsontherun.com Content-Length: 472047 Content-Disposition: attachment; filename="video.mpeg" Content-Type: application/octet-stream X-Content-Range: bytes 96296226-96768272/96768273 X-Session-ID: kwJei9j2vtQmcbojrlGJY3mbJFMHfzZwPXBwoSQr <bytes 96296226-96768272>
Example response after uploading the last file chunk¶
This is an example response of a successful video file upload.
<?xml version="1.0" encoding="UTF-8"?> <response> <status>ok</status> <video key="tL17msiU"> <size>96768273</size> </video> <redirect_link> <address>http://example.com/path/tL17msiU</address> <query> <parameter1>value1</parameter1> <parameter2>value2</parameter2> </query> </redirect_link> </response>
- /response/status : string
Upload status. Set to ok if upload was successfully.
- //video/@key : string
- //video/size : unsigned integer
Size of the received video file in bytes.
- //video/redirect_link/address : string
- //video/redirect_link/query/parameter : string
Redirect URL query parameter.
Resuming File Upload¶
If the file upload was interrupted due to the network connection issue or paused by the user, client should proceed with resuming the upload by uploading file chunk from the 0 byte position. Upload server will response with the combined byte range received in the previous upload session(s) and it will discard uploaded chunk if it has been received before. Client must use received byte range to determine start byte for the next file chunk. For example, if upload server responds with the received byte range 0-52370332/96768273, the next file chunk start byte must be 52370333.