Version: v4.5

Resumable File Upload

Overview#

The Resumable File Upload API allows you to complete the following actions:

Initiate, resume, or cancel a file upload
Retrieve file upload metadata

For more information, refer to the API Calls section.

File Status#

A file will have one of the following status types:

CREATED: The file is created in the database
UPLOAD_INITIATED: The file upload initiated in your file store, for example, an AWS S3 bucket.
UPLOAD_INTERRUPTED: The file upload is interrupted. An interruption can occur if the browser is closed, the internet disconnects, or any other reason.
UPLOAD_COMPLETED: The file is uploaded to your file store and is ready for download.

Notes on resumable file uploads#

Main steps#

Resumable file uploads involve two main steps:

Initiate file upload.
Resume file upload.

See detailed descriptions below of each step:

Step 1: Initiate file upload#

To initiate a resumable file upload, use the following request with the Initiate File Upload API call:

POST /files?uploadType=resumable&nsfilter={nsfilter}

See sample request body below with shows only mandatory fields for simplicity:

curl --location 'https://sandbox-api.invicara.com/filesvc/api/v1/files?uploadType=resumable&nsfilter=NestedFolderT11_6s6iuAQ2' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer <access_token>' \--data '{    "_name": "Solitaire Brochure.pdf",    "_namespaces": [        "NestedFolderT11_6s6iuAQ2"    ],    "_uploadMeta": {        "_size": 60861469,        "_checksum": "a9ab4ffea031aa9d2730818712c26582"    }}'

Upon success, a file is created with the status: UPLOAD_INITIATED.

Step 2: Resume file upload#

To resume the upload, use the following Resume File Upload API call, to ensure that the checksum matches the one used in Step 1:

PATCH /files/:id?uploadType=resumable&nsfilter={nsfilter}&checksum={checksum}

See sample request body below:

curl --location --request PATCH 'https://sandbox-api.invicara.com/filesvc/api/v1/files/2b4ba4d4-4388-4441-9047-6c90fc6c4eb3?uploadType=resumable&checksum=a9ab4ffea031aa9d2730818712c26582&nsfilter=NestedFolderT11_6s6iuAQ2' \--header 'Content-Type: application/pdf' \--header 'Authorization: Bearer <access_token>' \--data-binary '@/path/to/Solitaire Brochure.pdf'

If there is no interruption until the completion of the file upload then the status would be UPLOAD_COMPLETED, otherwise the status would be UPLOAD_INTERRUPTED.

Handling Interrupted Uploads#

If the upload is interrupted, the File Service maintains the offset where the upload stopped, with the status: UPLOAD_INTERRUPTED.

You can retrieve the offset using: HEAD /files/:id?uploadType=resumable

The response header will contain the Upload-Offset.

To resume the upload, use the PATCH request again with the required body starting from the offset value provided in the response header.

Uploading files in separate parts#

If you prefer to upload a file in separate parts, do the following:

Initiate upload request using POST /files/
Retrieve offset using HEAD /files/:id? (defaults to 0 if starting fresh)
Upload the first part of the file using PATCH /files/:id (Note: File parts must be at least 5 MB in size per PATCH request).
Retrieve the updated offset using HEAD /files:id
Upload the next part of the file using PATCH /files/:id (Send the next file part from the retrieved offset, not the offset from the previous PATCH request).

API Calls:#

This rest of this page lists the individual API calls which are available for the Resumable File Upload API.

Initiate File Upload#

This API call initiates a file upload.

Endpoints#

POST /filesvc/api/v1/files?uploadType=resumable

Request#

Parameters#

Query#

Parameter	Type	Description	Required
`uploadType`	String	Enter `resumable`.	Required
`nsfilter`	String	namespace context	Required

Request Headers#

The headers listed below will be used while downloading files.

Header	Type	Description	Required
`content-encoding`	String	Specify content encoding such as `gzip`	Optional
`content-type`	String	Specify content type such as `image/png`, `application/pdf`	Optional

Body#

Parameter	Type	Description	Required
`_name`	String	Enter the file's name as a string.	Required
`_namespaces`	Array of String	Pass an array with the namespaces that you want to contain the file.	Optional
`_parents`	Array of String	Pass the ids of parent folders you want to add the file to. If you do not add this property, the file adds to the root folder.	Optional
`_uploadMeta`	Object	Pass an object with `"_size"` and `"_checksum"` properties.	Required
`_uploadMeta._size`	Number	Enter the file size in bytes.	Required
`_uploadMeta._checksum`	Number	For data integrity, pass a string that represents the checksum value.	Required
`_tags`	Array of String	If you want to add metadata tags to your file, pass them as an array of strings with each string no longer than 50 characters. You can add a maximum of 10 tags.	Optional

Example request body

{  "_name": "test3.pdf",  "_namespaces": [    "xxxx_yyyy"  ],  "_tags": [    "tag1",    "tag2",    "tag3"  ],  "_parents": [    "678e5279-7354-4a9a-a3e6-deac7a6e5035"  ],  "_uploadMeta": {    "_size": 20702285,    "_checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709"  }}

Response#

Codes#

Code	Description
`201`	Created
`400`	Bad Request

Body#

Code example#

{  "_name": "test3.pdf",  "_tipId": "fcbc706f-c1f5-417a-b6d1-d7b7f22f1cb5",  "_type": "file",  "_irn": "filesvc:file:1b86d861-144f-4477-b83c-fa30bc728e57",  "_status": "UPLOAD_INITIATED",  "_parents": [    "678e5279-7354-4a9a-a3e6-deac7a6e5035"  ],  "_nextVersion": 5,  "_namespaces": [    "xxxx_yyyy"  ],  "_fileVersion": {    "_fileSize": 0,    "_id": "fcbc706f-c1f5-417a-b6d1-d7b7f22f1cb5",    "_metadata": {      "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",      "_createdByName": "xxxxxxxx",      "_createdAt": 1534931582091,      "_updatedByName": "xxxxxxx",      "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",      "_updatedAt": 1534931582091    },    "_version": 4,    "_fileId": "1b86d861-144f-4477-b83c-fa30bc728e57"  },  "_tipVersion": 4,  "_id": "1b86d861-144f-4477-b83c-fa30bc728e57",  "_uploadMeta": {    "_size": 20702285,    "_checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",    "_uploadId": "iB9Wy6AS19LbmYpTt8Ciu38nQ0WPs3LkM19ZYwj7aDSL8eCa6ZucoY.mua9Qo4WZ7bHDEZR_MFaLByOJ8GAw9d7qZJkpAlP5N59yJYk29gmjN18ZEZTzYv82Aib7lP26"  },  "_metadata": {    "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_createdByName": "xxxxxxxx",    "_createdAt": 1534930950783,    "_updatedByName": "xxxxxxxx",    "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_updatedAt": 1534931272631  }}

Get File Upload Metadata#

This API call retrieves the metadata associated with a file upload.

Endpoints#

HEAD /filesvc/api/v1/files/{id}?uploadType=resumable

Request#

Parameters#

Path#

Parameter	Type	Description	Required
`id`	String	The file's id	Required

Query#

Parameter	Type	Description	Required
`uploadType`	String	Enter `resumable`.	Required
`nsfilter`	String	namespace context	Required

Response#

Headers#

Key	Value
`Cache-Control`	`no-store`
`Upload-Length`	The file size in bytes
`Upload-Offset`	The number of bytes uploaded before the file upload was interrupted. For the 'UPLOAD_INITIATED' status, the value is `0`.

Resume File Upload#

Resumes a file upload.

Endpoints#

PATCH /filesvc/api/v1/files/{id}?uploadType=resumable

Request#

Parameters#

Path#

Parameter	Type	Description	Required
`id`	String	The file's id	Required

Query#

Parameter	Type	Description	Required
`uploadType`	String	Enter `resumable`.	Required
`checksum`	Number	For data integrity, pass a string that represents the checksum value.
Required
`nsfilter`	String	namespace context	Required

Body#

Parameter	Type	Description	Required
`file`	String	The file content, starting from the `Upload-Offset` value in the HEAD request.	Required

Response#

Codes#

Code	Description
`200`	Success
`404`	File Not Found

Body#

Code example#

{  "_name": "test3.pdf",  "_tipId": "fcbc706f-c1f5-417a-b6d1-d7b7f22f1cb5",  "_type": "file",  "_irn": "filesvc:file:1b86d861-144f-4477-b83c-fa30bc728e57",  "_status": "UPLOAD_INITIATED",  "_parents": [    "678e5279-7354-4a9a-a3e6-deac7a6e5035"  ],  "_nextVersion": 5,  "_namespaces": [    "iput_11b7Ke8j"  ],  "_fileVersion": {    "_fileSize": 0,    "_id": "fcbc706f-c1f5-417a-b6d1-d7b7f22f1cb5",    "_metadata": {      "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",      "_createdByName": "xxxxxxx",      "_createdAt": 1534931582091,      "_updatedByName": "xxxxxxx",      "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",      "_updatedAt": 1534931582091    },    "_version": 4,    "_fileId": "1b86d861-144f-4477-b83c-fa30bc728e57"  },  "_tipVersion": 4,  "_id": "1b86d861-144f-4477-b83c-fa30bc728e57",  "_uploadMeta": {    "_size": 20702285,    "_checksum": "da39a3ee5e6b4b0d3255bfef95601890afd80709",    "_uploadId": "iB9Wy6AS19LbmYpTt8Ciu38nQ0WPs3LkM19ZYwj7aDSL8eCa6ZucoY.mua9Qo4WZ7bHDEZR_MFaLByOJ8GAw9d7qZJkpAlP5N59yJYk29gmjN18ZEZTzYv82Aib7lP26"  },  "_metadata": {    "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_createdByName": "xxxxxxxx",    "_createdAt": 1534930950783,    "_updatedByName": "xxxxxxxx",    "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_updatedAt": 1534931272631  }}

Cancel File Upload#

This API call cancels a file upload that is in progress and removes it from your file store.

Endpoints#

DELETE /filesvc/api/v1/files/{id}?uploadType=resumable

Parameters#

Path#

Parameter	Type	Description	Required
`id`	String	The file's id	Required

Query#

Parameter	Type	Description	Required
`uploadType`	String	Enter `resumable`.	Required
`nsfilter`	String	namespace context	Required

Response#

Codes#

Code	Description
`200`	Success
`204`	No Content
`404`	File Not Found

Body#

The following response body returns with a 200 response code:

Code example#

{  "_nextVersion": 3,  "_namespaces": [    "iput_11b7Ke8j"  ],  "_previews": [],  "_name": "test4.pdf",  "_tipVersion": 2,  "_tipId": "bfd46648-635f-41c9-8ecb-7c34bbc4e801",  "_type": "file",  "_irn": "filesvc:file:e7ea91e4-7465-4e1b-9277-3a82e676ab0e",  "_id": "e7ea91e4-7465-4e1b-9277-3a82e676ab0e",  "_status": "UPLOAD_COMPLETED",  "_metadata": {    "_updatedById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_createdByName": "xxxxxxx",    "_createdAt": 1534934439376,    "_updatedByName": "xxxxxxx",    "_createdById": "35c74e68-32e2-47ae-8be6-c37aa0ac9976",    "_updatedAt": 1534934803712  },  "_parents": [    "678e5279-7354-4a9a-a3e6-deac7a6e5035"  ]}