createResumableUpload

Overview

This endpoint can be used for creating a resumable upload endpoint, allowing for the robust transfer of large files to Redivis.
This endpoint should be called before calling upload.post. First create a resumable upload here, then upload your file as described below, and then finally create your upload with the resumable upload's id in the payload.
Resumable uploads can be quite complex. It is highly recommended to use one of the client libraries to upload your files (and handle resumable uploads for you), rather than calling this endpoint directly.

HTTP Request

1
POST /api/v1/tables/:tableReference/resumableUpload
Copied!

Path parameters

Parameter
tableReference
A qualified reference to the table. See referencing resources for more information.

Query parameters

Parameter
Text
size
Required. The size of the upload, in bytes

Request body

This endpoint extends the general API structure.

Authorization

Edit access to the table's dataset is required. Your access token must have one of the following scopes:
  • data.edit
The request body must be empty.

Response body

Returns the url and id for the resumable upload.
1
{
2
"kind": "resumableUpload",
3
"id": string,
4
"url": string
5
}
Copied!

Performing the resumable upload

1
PUT <resumableUpload.url>
Copied!

Overview

The general process for performing a resumable upload is to send the file in a series of chunks, via PUT requests to the url returned when creating the resumable upload. For each request, specify the Content-Range header to inform which chunk is currently being uploaded, and provide the content of the chunk in the request body.
If an error occurs when uploading a chunk, you can retry the upload as specified below.
Resumable uploads expire after 24 hours.

Request headers

Header
Description
Content-Range
Set to show which bytes in the file you are uploading.
For example, Content-Range: bytes 0-524287/2000000 shows that you are uploading the first 524,288 bytes (256 x 1024 x 2) in a 2,000,000 byte file.
If the total file size isn't known beforehand (for example, during streaming uploads that might perform processing on the stream), you can specify an unknown total size as: Content-Range: bytes 0-524287/*
If you are resuming an interrupted upload and want to know its progress, set the left part of the range to a * to signal that it is unknown. E.g., Content-Range: bytes */2000000

Request body

You should provide the current chunk content in the request body.

Response body

Upon successfully transferring a chunk, the response body will be empty with a status of 200.

Resuming an interrupted upload

If an upload request is terminated before receiving a response, or if you receive a 503 or 500 Service Unavailable response, then you need to resume the interrupted upload. To resume an interrupted upload:
  1. 1.
    To request the upload status, create an empty PUT request to the resumable session URI.
  2. 2.
    Add a Content-Range header indicating that the current position in the file is unknown. For example, set the Content-Range to */2000000 if your total file length is 2,000,000 bytes. If you don't know the full size of the file, set the Content-Range to */*.
  3. 3.
    Send the request.
  4. 4.
    Process the response.
    A 200 OK or 201 Created response indicates that the upload was completed, and no further action is necessary. A 308 Resume Incomplete response indicates that you need to continue uploading the file.
  5. 5.
    If you received a 308 Resume Incomplete response, process the response's Range header, which specifies which bytes Cloud Storage has received so far. You will use this number in the next step. The response does not have a Range header if Cloud Storage has not yet received any bytes. For example, a Range header of bytes=0-42 indicates that the first 43 bytes of the file have been received.
  6. 6.
    Now that you know where to resume the upload, continue uploading the file, either by sending the remaining data or by sending the next chunk. Include a Content-Range header indicating which portion of the file you are sending. For example, Content-Range: bytes 43-1999999/2000000 indicates that you are sending bytes 43 through 1,999,999.
Last modified 4mo ago