While uploading files to the network, some problems, such as interruptions, slowdowns, and outages, can cause the process to be lost. This can lead to problems for developers, in particular when using APIs. For instance, you might be uploading an audio or video file through the API of ArvanCloud’s video hosting platform and because of a temporary outage of the internet, a problem may arise with the connection to ArvanCloud’s servers. In this way, coupled with the inability to resume the upload process, you will have to start uploading the file again, which is not good at all.

In an effort to make file uploading easier and offer the option to continue uploading following a disconnection, a protocol called TUS has been developed. Through the use of this open-source protocol, the upload of files to ArvanCloud’s video hosting platform will be resumable. When the connection is broken for any reason during an upload process step, it will be possible to continue resuming the process at the point where it was left off.

Based on HTTPS/HTTP, the TUS protocol has been designed and developed for multiple platforms, such as desktop and mobile browsers and applications. The unique feature of this project is the utilization of a custom protocol for both client and server deployments.

Within this technical guide, we are going to explore how to use the TUS protocol, in particular, to work with the ArvanCloud Video Hosting Platform API. In addition, you can check out the documentation on how to implement this protocol on the TUS website.

Requests in TUS

The HEAD request is used to indicate where the upload offset should continue. Below is an example of how far a 100 byte file has been uploaded. You can use the PATCH request to resume the upload at the point where the upload left off.

Request

HEAD /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1 
Host: tus.example.org 
Tus-Resumable: 1.0.0

Response

HTTP/1.1 200 OK 
Upload-Offset: 70 
Tus-Resumable: 1.0.0

Using Upload-Offset you can resume uploading the file from where it was left off. For Example:

PATCH /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1 
Host: tus.example.org 
Content-Type: application/offset+octet-stream 
Content-Length: 30 
Upload-Offset: 70 
Tus-Resumable: 1.0.0 [remaining 30 bytes]

Then you will receive a response as below.

HTTP/1.1 204 No Content 
Tus-Resumable: 1.0.0 
Upload-Offset: 100

TUS Protocol Headers

Headers are extremely important in the TUS protocol. You will learn some of the most important headers of this protocol in the following section.

  • Upload-Offset: Indicates the number of bytes uploaded (offset) and has to be a positive number.
  • Upload-Length: This shows the total size of the uploaded file (bytes) and has to be a positive number.
  • Tus-version: You may enter the latest version or, with a comma, enter the list of versions supported by the protocol. This list must be entered according to the most recent versions, for example:
Tus-Version: 1.0.0,0.2.2,0.2.1
  • Tus-Resumable: Note that this header should be present in all requests/responses with the exception of OPTIONS, and its value has to match the version of the protocol used by the server or client. In addition, a 412 Precondition Failed error will be shown if the version is not supported. For example:
 Tus-Resumable: 1.0.0 
Tus-Version: 1.0.0,0.2.2,0.2.1
  • Tus-Max-Size: A positive number that indicates the file upload limit in bytes.
  • Upload-metadata: Its value should consist of one or more key-value separated by commas. The specified key and value should be separated by a space, and the key must be ASCII-encoded, and the value has to be Base64-encoded. As an example, for a file named video.mp4:
Upload-metadata: filename dmlkZW8ubXA0,filetype dmlkZW8vbXA0

This example has the above values set because the base64 conversion of the video.mp4 file is equal to dmlkZW8ubXA0, and the base64 conversion of the video/mp4 file is equal to dmlkZW8vbXA0. To check others, you can use websites like base64encode. In this example, the server’s response to create the file is 201, and the URL of the file is added to the Response header in the Location section.