Version: v5.1

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"
  ]
}

Overview​

File Status​

Notes on resumable file uploads​

Main steps​

Step 1: Initiate file upload​

Step 2: Resume file upload​

Handling Interrupted Uploads​

Uploading files in separate parts​

API Calls:​

Initiate File Upload​

Endpoints​

Request​

Parameters​

Query​

Request Headers​

Body​

Response​

Codes​

Body​

Code example​

Get File Upload Metadata​

Endpoints​

Request​

Parameters​

Path​

Query​

Response​

Headers​

Resume File Upload​

Endpoints​

Request​

Parameters​

Path​

Query​

Body​

Response​

Codes​

Body​

Code example​

Cancel File Upload​

Endpoints​

Parameters​

Path​

Query​

Response​

Codes​

Body​

Code example​

Overview

File Status

Notes on resumable file uploads

Main steps

Step 1: Initiate file upload

Step 2: Resume file upload

Handling Interrupted Uploads

Uploading files in separate parts

API Calls:

Initiate File Upload

Endpoints

Request

Parameters

Query

Request Headers

Body

Response

Codes

Body

Code example

Get File Upload Metadata

Endpoints

Request

Parameters

Path

Query

Response

Headers

Resume File Upload

Endpoints

Request

Parameters

Path

Query

Body

Response

Codes

Body

Code example

Cancel File Upload

Endpoints

Parameters

Path

Query

Response

Codes

Body

Code example