Upload Object

General

Uploading an object consists of 3 main steps:

1. Initializing an upload.
2. Uploading all the object data.
3. Completing the upload.

Uploading the object data (step 2) can be done in two different ways:

• PUT /objects/{key}/stream: Stream the entire object from start to end in a continuous request.
• PUT /objects/{key}/part: Chunk the object locally and upload each chunk individually.

Both have their own pros and cons:

PUT /objects/{key}/stream:

• + Makes only one endpoint call.
• + No local pre-processing required.
• - Susceptible to network instabilities.

PUT /objects/{key}/part:

• + More robust. Each part can be retried individually.
• + Parts can be uploaded in parallel.
• - Require local processing/splitting.

There is no "best choice". Factors such as upload speed, network stability and client side handling are considerations to take when choosing upload method.

For full endpoints details, please refer to the Swagger documentation.

General Flow

---
title: Upload object flow
---
sequenceDiagram
    Sender ->>+ DEFT: POST /objects/initialization
    DEFT ->>- Sender: Returns key + initialization info

    alt Stream entire object
        Sender ->>+ DEFT: PUT /objects/{key}/stream
        DEFT ->>- Sender: 200 OK + upload info
    else Upload in chunks
        loop Until all parts are uploaded
            Sender ->>+ DEFT: PUT /objects/{key}/part
            DEFT ->>- Sender: 200 OK + upload info
        end
    end

    Sender ->>+ DEFT: POST /objects/{key}/completion
    DEFT ->>- Sender: Returns key + location

Initialize an Object Upload

Call the POST /objects/initialization endpoint to initialize an object upload.

Returns a key and UploadId to be used in further requests.

The initialization request must contain information about the sender, receiver and a filename.

File Name Restrictions

These rules apply to file names:

• Max length of 100 characters.
• Allowed characters: most alphanumerics, hyphen -, underscore _, parentheses ( ), and spaces .
• A single period . is allowed, but only to separate the file name from the extension.

These recommendations apply to file names:

• Do not include personal or sensitive information in the file name.

Stream the Entire Object

Call the PUT /objects/{key}/stream endpoint to stream an entire object's contents to an initialized upload.

Returns a list of all internally created parts, which is requires to complete the upload.

Upload Parts in Chunks

Call the PUT /objects/{key}/part endpoint to upload a part of an object to an initialized upload.

You must provide a part number.

The responses from all PUT /objects/{key}/part requests are required to complete the upload.

Complete an Object Upload

Call the POST /objects/{key}/completion endpoint to complete an initialized upload.

All the response data from PUT /objects/{key}/stream or PUT /objects/{key}/part must be provided in order to complete the upload.

A successful response contains a location header.

Cancel an Object Upload

Call the POST /objects/{key}/cancellation endpoint to cancel an initialized upload.

Any data uploaded will be discarded.