Create multipart file

A multipart upload allows a file to be uploaded in parts. Multipart uploads are resumable uploads.

After each part is uploaded, the complete action recompiles the parts. The file then becomes accessible under a unique file ID and path, with a single URL for downloading.

• The minimum size for a multipart upload part is 5 MB (except for the last part, which may be less than 5 MB).
• The maximum part size is 5 GB.
• The number of parts of a multipart upload cannot exceed 10,000.

Prerequisites

• A space should be created. To know more about creating a space refer here
• File needs to be segregated for multipart upload.

Use the following steps to upload a multipart file to File service.

The steps below provide an outline. See File service API definition for parameter details.

1. Create a new upload file object

Request

POST {baseUrl}/spaces/{spaceId}/uploads

• HEADER:

  • Authorization: Bearer {tid token}

• BODY:

  • name - Name of file
  • parentId - Parent id for the file where it needs to be created
  • multipart - Boolean value to indicate if the file needs to be created as a multipart file

Example request body:

       {
           "name" : "test",
           "parentId" : "e492c129-141d-4679-b0a7-829580679b6a",
           "multipart" : true
       }

Response

After the upload operation is completed, the JSON response includes the id value for the file and URLs for your file upload.

Example response:

{
       "createdAt": "2024-06-24T09:31:19Z",
       "createdByTrn": "trn:tid:application:fae7a6aa-cf9b-42ad-945b-a89d1c1ec580",
       "fileInputUploadDetails": {
           "acl": {
               "contentManager": [
                   "trn:tid:application:fae7a6aa-cf9b-42ad-945b-a89d1c1ec580"
               ]
           },
           "fileId": "e492c129-141d-4679-b0a7-829580679b6a",
           "fileset": false,
           "metadata": {
               "testkey": "testvalue"
           },
           "multipart": true,
           "name": "Hettingerstad",
           "parentId": "24f92ed9-74be-4556-bfb3-ab037fdb08a1",
           "path": "/test125/Hettingerstad",
           "restrictedAccess": false,
           "spaceId": "cbbf270b-a8cb-450b-8192-495cf252d921",
           "upload": {
               "type": "MULTIPART",
               "url": "https://us-aws-wo.dev.fileservice.trimblecloud.com/fs_s/e492c129-141d-4679-b0a7-829580679b6a.a257f7d4-5fd8-4300-8d9a-1b611771be4b?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly91cy1hd3Mtd28uZGV2LmZpbGVzZXJ2aWNlLnRyaW1ibGVjbG91ZC5jb20vZnNfcy9lNDkyYzEyOS0xNDFkLTQ2NzktYjBhNy04Mjk1ODA2NzliNmEuYTI1N2Y3ZDQtNWZkOC00MzAwLThkOWEtMWI2MTE3NzFiZTRiIiwiQ29uZGl0aW9uIjp7IkRhdGVMZXNzVGhhbiI6eyJBV1M6RXBvY2hUaW1lIjoxNzE5MjI1MDc5fX19XX0_&Signature=PGejC2lqBmwoBieqdcyE3xUNx6XQ9tb1GJxHCBGmdknA~5KYj11W37m6JebYBJNjfY~d2WFNzLuNZKLLudCM57CmM3pIWaGBinDN3Msb5dz3gmbBVQeGw1pwDQZFV66fdgCmcA6iYzpNeAaqmEZt-AnBqpQbBTA8IC~Y2OlxSnRMwFM5v4iD4e2Uifxj0zymVTEaKKoZhNLVi3x5EqmCMZrCdG3AQncwdqbqoNlRdysNPg0m01jGRNBUdWIDg6oK-GlS5WWdj3NC0BTwxWe-moGFT9YXiAZn3ZTOUpwSIbmDy~uLjAmUVSmdilpho37Pko9LO5WpbBe2ixUnc1a4FQ__&Key-Pair-Id=APKAI6JAFOBXQEFCLCSQ"
           }
       },
       "id": "a257f7d4-5fd8-4300-8d9a-1b611771be4b",
       "updatedAt": "2024-06-24T09:31:19Z",
       "updatedByTrn": "trn:tid:application:fae7a6aa-cf9b-42ad-945b-a89d1c1ec580"
   }

2. Upload file parts

There is a query string parameter “partNumber=*” in the upload URL from the previous request. Substitute the “*” value with the number of the current part that needs to be uploaded.

Separate the file into parts, and upload each to the URL with parameter value substituted. Part numbering starts with "1" (not zero).

Request

PUT {UPLOAD URL}

• BODY

{PART DATA}

Response will include an ETag in the header. Keep track of the ETag responses for each upload.

3. Run complete multipart API call

After all parts are uploaded, run the API call to complete the multipart upload. Use the upload id from the first step.

Request

PATCH /spaces/{spaceId}/uploads/{uploadId}

• HEADER:

  • Authorization: Bearer {tid token}

• BODY:

  • etag - ETag generated from aws
  • partNumber - Part number of the uploaded file

Example request body:

{
      {
      "parts": [
            {
              "etag": "107a11224699641f1366c00ddac5e06b",
              "partNumber": "1"
            },
            {
              "etag": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
              "partNumber": "2"
            }
      ]
    }
}

Response

Example response:

{
  "id": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
  "fileInputUploadDetails": {
    "fileId": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
    "spaceId": "f85bc802-5481-4581-b972-c4652d595ec7",
    "name": "FileName.ext",
    "acl": {
      "contentManager": [
        "trn:tid:user:6529d0b3-5856-41ab-88b3-86f7955cddf1",
        "trn:tid:user:7529d0b3-5856-41ab-88b3-86f7955cddf1"
      ],
      "contentContributor": [
        "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7",
        "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7"
      ],
      "contentViewer": [
        "trn:tid:device:8529d0b3-5856-41ab-88b3-86f7955cddf1"
      ]
    },
    "parentId": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
    "path": "testA/testB/FileName.ext",
    "fileset": false,
    "restrictedAccess": false,
    "expiresAt": "2024-01-01T12:25:00.000Z",
    "metadata": {
      "language": "Suomi"
    },
    "multipart": true,
    "responseHeaders": {
      "response-content-type": "image/jpeg",
      "response-content-disposition": "inline",
    },
    "applicationId": "f85bc802-5481-4581-b972-c4652d595ec7"
  },
  "result": {
    "message": "Upload job is COMPLETED",
    "status": "COMPLETED"
  },
  "createdAt": "2023-05-30T10:30:00Z",
  "createdByTrn": "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7",
  "updatedAt": "2023-05-30T10:30:00Z",
  "updatedByTrn": "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7"
}

4. Validate the upload

Run a GET upload API call to check the job status. The value should be COMPLETED.

Request

GET {baseUrl}/spaces/{spaceId}/uploads/{uploadId}

• HEADER:

  • Authorization: Bearer {tid token}

Response

Example response:

{
"id": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
"fileInputUploadDetails": {
    "fileId": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
    "spaceId": "f85bc802-5481-4581-b972-c4652d595ec7",
    "name": "FileName.ext",
    "acl": {
    "contentManager": [
        "trn:tid:user:6529d0b3-5856-41ab-88b3-86f7955cddf1",
        "trn:tid:user:7529d0b3-5856-41ab-88b3-86f7955cddf1"
    ],
    "contentContributor": [
        "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7",
        "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7"
    ],
    "contentViewer": [
        "trn:tid:device:8529d0b3-5856-41ab-88b3-86f7955cddf1"
    ]
    },
    "upload": {
    "url": "https://example.com/upload/12345678-90ab-cdef-1234-567890abcdef.1",
    "type": "SINGLEPART"
    },
    "parentId": "e28982f5-ebd8-4a76-97f4-0783fc143f30",
    "path": "testA/testB/FileName.ext",
    "fileset": false,
    "restrictedAccess": false,
    "expiresAt": "2024-01-01T12:25:00.000Z",
    "metadata": {
    "language": "Suomi"
    },
    "multipart": true,
    "responseHeaders": {
    "response-content-type": "image/jpeg",
    "response-content-disposition": "inline",
    "response-cache-control": "max-age=3000"
    },
    "applicationId": "f85bc802-5481-4581-b972-c4652d595ec7"
},
"createdAt": "2023-05-30T10:30:00Z",
"createdByTrn": "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7",
"updatedAt": "2023-05-30T10:30:00Z",
"updatedByTrn": "trn:tid:application:f85bc802-5481-4581-b972-c4652d595ec7"
}

To know more about the upload multipart API refer here.